Հանրային API & API բանալիներ

Ծրագրային հասանելիություն ձեր աշխատանքային տարածքին — կարդացեք նախագծերը, աշխատաշրջանները, հատուկ իրադարձություններն ու հատվածները և հաճախորդների ID-ներ կցեք աշխատաշրջաններին — պաշտպանված աշխատանքային տարածքի շրջանակի API բանալիներով։

1. Ակնարկ

MousePlayer API-ն թույլ է տալիս աշխատանքային տարածքից տվյալներ ստանալ ձեր վահանակների, պահեստի կամ ներքին գործիքների մեջ։ Բացի հաճախորդների ID-ներն աշխատաշրջաններին կցելուց՝ identify, պահանջում է գրելու շրջանակի բանալի, տես Բանալու շրջանակները, այն միայն կարդալու համար է. API-ով տվյալներ հնարավոր չէ փոփոխել կամ ջնջել։

Հիմնական URL՝ https://www.mouseplayer.com/api/v1/
Բոլոր պատասխանները JSON են։
Յուրաքանչյուր հարցում նույնականացվում է API բանալիով և ինքնաբերաբար սահմանափակվում է դրա աշխատանքային տարածքով — մեկ տարածքի բանալին երբեք չի կարող տեսնել մյուսի տվյալները՝ նույնիսկ պատահմամբ։
Աշխատաշրջանի ամբողջական ձայնագրությունը՝ մկնիկի շարժումներ, DOM պատկերներ, չի տրամադրվում API-ով։ Ստանում եք աշխատաշրջանի մետատվյալներ, էջադիտումներ, հատուկ իրադարձություններ և հատվածներ — բավարար՝ հաշվետվություններ ու վահանակներ կառուցելու համար՝ առանց չմշակված ձայնագրության բեռը փոխանցելու։

2. Նույնականացում

API բանալիները ստեղծեք ու կառավարեք ձեր հաշվի ընտրացանկի API բանալիներ բաժնում (/api-keys)։ Միայն սեփականատերերն ու ադմինիստրատորները կարող են բանալիներ ստեղծել կամ հետ կանչել։

Բանալին գաղտնի պահեք։ Այն ընթերցման հասանելիություն է տալիս տարածքի ամբողջ բովանդակությանը։ Ամբողջական բանալին ցուցադրվում է ճիշտ մեկ անգամ՝ ստեղծելուց անմիջապես հետո — պահեք գաղտնաբառերի կառավարչում կամ գաղտնիքների պահոցում։ Կորցնելիս հետ կանչեք և նորը ստեղծեք։

Յուրաքանչյուր հարցման Authorization վերնագրում բանալին ուղարկեք որպես Bearer թոքեն՝

# List projects in your workspace curl -H "Authorization: Bearer mp_live_..." \ https://www.mouseplayer.com/api/v1/projects

Բացակայող, սխալ ձևավորված կամ հետ կանչված բանալիները ստանում են 401 պատասխան՝

{ "error": "Invalid or missing API key. Use: Authorization: Bearer <key>" }

Պլանի պահանջ

REST API-ն ներառված է Business և Enterprise պլաններում։ Պլանը վերցվում է աշխատանքային տարածքի սեփականատիրոջից , ուստի հրավիրված անդամները ժառանգում են այն։ Ստուգումը կատարվում է յուրաքանչյուր հարցման ժամանակ, ոչ միայն բանալու ստեղծման պահին — եթե տարածքի պլանը նվազեցվում է, առկա բանալիները դադարում են աշխատել և վերադարձնում են 403։

Բանալու շրջանակները

Յուրաքանչյուր բանալի իր շրջանակը կրում է նախածանցում, ուստի տեսքից պարզ է՝ ինչ է անում — .env-ում, հայտում կամ տերմինալում։

Նախածանց	Իմաստ
`mp_ro_`	Միայն ընթերցում։ Կարդում է նախագծերը, աշխատաշրջանները, իրադարձություններն ու հատվածները։ Ոչինչ չի կարող փոխել։
`mp_rw_`	Ընթերցում և գրառում։ Վերոնշյալն ամբողջությամբ՝ նաև հաճախորդների ID-ների կցում identify վերջնակետով։

Շրջանակն ընտրեք բանալին ստեղծելիս. լռելյայնը միայն ընթերցումն է։ Գրող վերջնակետում միայն ընթերցման բանալի օգտագործելը վերադարձնում է 403 ՝ հաղորդագրությամբ, որը նշում է բանալու տեսակը և վերջնակետի պահանջը։ Շրջանակը հետո չի փոխվում — ստեղծեք նոր բանալի և հետ կանչեք հինը։

3. Հարցումների հաճախականության սահմաններ

Յուրաքանչյուր API բանալի սահմանափակված է՝ րոպեում 60 հարցում՝ շարժական պատուհանով հաշվարկված։ Գերազանցելուց հետո հարցումները ստանում են 429 պատասխան՝ մինչև պատուհանի մաքրվելը՝

{ "error": "Rate limit exceeded. Max 60 requests per minute." }

Ավելի բարձր սահման պահանջող բա՞ն եք կառուցում։ Կապվեք Աջակցության միջոցով և պատմեք ձեր կիրառման դեպքի մասին։

4. Վերջնակետեր

GET/api/v1/projects

Թվարկում է աշխատանքային տարածքի բոլոր նախագծերը՝ հետևվող կայքերը։

{ "data": [ { "channelid": "955a45df5ee842cb", "domain": "yourdomain.com", "status": "active", "total_traffic_bytes": 27304765, "created_at": "2026-07-19 22:06:39", "last_used": "2026-08-05 01:12:55" } ] }

GET/api/v1/projects/{channelid}/sessions

Թվարկում է նախագծի գրանցված այցելուի աշխատաշրջանները՝ նորերից սկսած։ Էջավորված է։

Հարցման պարամետր	Նկարագրություն
`page`	Էջի համարը, լռելյայն՝ `1`։
`per_page`	Արդյունքներ մեկ էջում, լռելյայն՝ `25`, առավելագույնը՝ `100`։
`since`	Միայն այս ամսաթվին կամ դրանից հետո սկսված աշխատաշրջանները (`YYYY-MM-DD`)։
`until`	Միայն այս ամսաթվին կամ դրանից առաջ սկսված աշխատաշրջանները։

{ "data": [ { "session_id": "s_kfmist058_1785795295504", "visitor_id": "v_sv90jdpzo_1785795296042", "custom_user_id": null, "country": "DE", "device_type": "desktop", "is_bot": 0, "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105 } ], "pagination": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 } }

GET/api/v1/sessions/{session_id}

Մեկ աշխատաշրջանի մետատվյալները և դրա էջադիտումները։ Ամբողջական ձայնագրության բեռը միտումնավոր բացառված է — դրա համար օգտագործեք վահանակի նվագարկիչը։

{ "data": { "session_id": "s_kfmist058_1785795295504", "channelid": "955a45df5ee842cb", "visitor_id": "v_sv90jdpzo_1785795296042", "country": "DE", "asn_org": "Deutsche Telekom AG", "referrer": "https://duckduckgo.com/", "device_type": "desktop", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105, "pageviews": [ { "pageview_id": 1199, "url": "https://yourdomain.com/pricing", "page_title": "Pricing", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41" } ] } }

GET/api/v1/sessions/{session_id}/events

Աշխատաշրջանի ընթացքում կատարված հատուկ իրադարձությունները՝ նույնը, ինչ ուղարկում եք mp('event', ...)-ով, ներառյալ պարամետրերը։

{ "data": [ { "event_id": 61, "pageview_id": 1199, "event_name": "add_to_cart", "created_at": "2026-08-04 00:14:59", "params": { "item_id": "SKU_98765", "price": 299.99 } } ] }

GET/api/v1/projects/{channelid}/segments

Թվարկում է նախագծի համար սահմանված այցելուների հատվածները՝ թե՛ նախագծային, թե՛ ամբողջ աշխատանքային տարածքի։

{ "data": [ { "segment_id": 4, "name": "High Intent Visitors", "description": "Pageviews > 5", "badge_color": "cyan", "is_global": 0, "created_at": "2026-08-03 00:00:43" } ] }

5. Հաճախորդի ID-ի կցում ձեր սերվերից

Դիտարկիչը հաճախ չգիտի՝ ով է նստած։ B2B արտադրանքում ինքնությունը հաստատվում է մուտքից հետո — ձեր սերվերում։ Խանութում՝ պատվերի հաստատմամբ։ Այս վերջնակետը հենց այդ պահի համար է։

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

ID-ն հայտնվում է աշխատաշրջանների ցանկում, այնտեղ որոնելի է դառնում, և գործարկվում է session_identified webhook-ը — այսպես այն հասնում է CRM-ին։

Նույն ID-ով երկու անգամ կանչելն անվտանգ է։ Պատասխանը վերադառնում է "changed": false -ով, և webhook չի ուղարկվում։ Կրկնվող պատվերը երկրորդ պոտենցիալ հաճախորդ չի ստեղծում։

Վիճակ	Երբ
`400`	Դաշտը բացակայում է, `user_id` գերազանցում է 128 նիշը կամ պարունակում կառավարման նիշեր։ Կտրելու փոխարեն մերժում ենք — լուռ կրճատված ID-ն CRM-ում ոչնչի չի համապատասխանում, բայց հաջողության տեսք ունի։
`404`	Աշխատաշրջանը գոյություն չունի կամ չի պատկանում ձեր տարածքին։ Երկուսի համար էլ միտումնավոր նույն պատասխանն է։
`403`	Տարածքի պլանը չի ներառում API-ն։

6. Webhook-ներ. ստորագրության ստուգում

Webhook-ները յուրաքանչյուր նախագծի համար կարգավորվում են Ինտեգրումներբաժնում, որտեղ նաև ստորագրման գաղտնիքն է։ Յուրաքանչյուր առաքում կրում է հետևյալ վերնագրերը՝

Վերնագիր	Իմաստ
`X-MousePlayer-Event`	Իրադարձության անուն, օրինակ՝ `session_identified`
`X-MousePlayer-Timestamp`	Unix վայրկյաններ — ստորագրված տեքստի մաս
`X-MousePlayer-Attempt`	1՝ առաջին փորձին, ավելի բարձր՝ կրկնակի փորձերին
`X-MousePlayer-Signature`	`sha256=<hex>`

Ստորագրությունը HMAC-SHA256 է՝ հաշվարկված հետևյալի վրա՝ timestamp + "." + raw body՝ ձեր նախագծի ստորագրման գաղտնիքով։

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

Ստորագրեք չմշակված մարմինը՝ մինչև JSON վերլուծումը։ Կրկին սերիալացնելը փոխում է բանալիների հերթն ու բացատները, և ստորագրությունը երբեք չի համընկնի։ Մերժեք նաև մի քանի րոպեից հին ժամանակադրոշմով ամեն ինչ — հենց դրա համար է ժամանակադրոշմը։

Առաքում և կրկնակի փորձեր

Ձախողված առաքումը կրկնվում է հետևյալ ընդմիջումներից հետո՝ 1 րոպե, 5 րոպե, 15 րոպե, 1 ժամ և 6 ժամ, ապա դադարեցվում է։ 4xx Պատասխանները, բացի 408 և 429 -ից, չեն կրկնվում — ասում են "ոչ այսպես", ոչ թե "ոչ հենց հիմա"։ Արագ պատասխանեք 2xx և աշխատանքը հետո արեք. առաքման ժամկետը սպառվում է 10 վայրկյան անց։

Հասանելի իրադարձություններ

Իրադարձություն	Գործարկվում է
`session_identified`	Երբ աշխատաշրջանն առաջին անգամ հաճախորդի ID է ստանում — դիտարկիչից կամ API-ից
`session_ended`	Մեկ անգամ՝ աշխատաշրջանի փակվելիս
`goal_reached`	Մեկ անգամ աշխատաշրջանի համար՝ երբ հատուկ իրադարձությունը կատարում է նպատակներից մեկը։ Միայն «event» տիպի նպատակներ — URL-ի, տևողության, էջադիտման և ձագարի նպատակները չեն գնահատվում։ Կրում է `goal_id`, `goal_name`, `goal_value` և `currency`։
`high_value_session`	Երբ այցելուն տվյալ օրվա ընթացքում առաջին անգամ անցնում է այս նախագծի արժեքի շեմը։ Շեմը ստացվում է ձեր սեփական գնահատականների բաշխումից ՝ վերջին 90 օրվա 90-րդ տոկոսականը, ոչ հաստատուն թիվ, և չկա՝ մինչև առնվազն 20 այցելու գնահատված լինի։ Կրում է `visitor_id`, `value_score`, `threshold` և այդ օրվա ամենադիտարժան աշխատաշրջանը։
`funnel_dropoff`	Այն աշխատաշրջանի վերջում, որը մտել է ձագարներից մեկը, բայց չի ավարտել։ Նշում է կանգ առած քայլը (`dropped_at`)։ Լքումը իրադարձության բացակայություն է, ուստի հայտնի է միայն աշխատաշրջանի ավարտից հետո։ Ձագար երբեք չմտած աշխատաշրջանները լքումներ չեն և չեն գործարկում։
`high_friction_session`	Մեկ անգամ աշխատաշրջանի համար՝ երբ խոչընդոտի գնահատականն առաջին անգամ հասնում է շեմին՝ լռելյայն 60՝ 100-ից։ Կրում է `friction_score`, հիմքում եղած ազդանշանները (`reasons`) և շեմն անցած ազդանշանը (`trigger`)։
`element_broken`	Մեկ անգամ՝ երբ հետևվող նշումը մի քանի օր ոչինչ չի գտնում ստուգված էջադիտումներում — սովորաբար վերաթողարկումից հետո։ Կրկին գործարկվում է միայն, երբ նշումը համընկել և կրկին խափանվել է։ Այս իրադարձությունը պատկանում է ոչ մի աշխատաշրջանի՝ `session_id` և `session_url` արժեքներն են՝ `null`, `link_url` փոխարենը բացում է նշումը, իսկ `subject_id` անվանում է նշումը — նույնը բոլոր տարբերակներում, որպեսզի նորից խափանված նոր ընտրիչը միանա բաց միջադեպին։ Կրում է `rule_id`, `rule_name`, `selector`, `page`, `checked_page_views`, `window_days` և `last_matched`։ Այցելուի տվյալներ չկան։
`element_recovered`	Խնդրի վերացման ազդանշան՝ `element_broken`համար, երբ նշումն իսկապես կրկին տարր է գտնում — քիչ էջադիտումները բավարար չեն։ Ուղարկվում է միայն, եթե `element_broken` -ն ուղարկվել է webhook-ով, և առանձին անջատիչ չունի. բաժանորդագրվելը `element_broken` -ին ներառում է նաև սա։ Նույն `subject_id`-ով PagerDuty-ն լուծում է միջադեպը, Opsgenie-ն փակում ահազանգը։ Լրացուցիչ կրում է `matched_page_views` և `checked_page_views` ։
`anomaly_detected`	Օրը մեկ անգամ՝ երբ երեկը հստակ տարբերվել է նախորդ 28 օրերից. զգալիորեն պակաս կամ շատ աշխատաշրջաններ, ընկած նպատակի ցուցանիշ, ավելի շատ խոչընդոտով կամ JS սխալներով աշխատաշրջաններ։ Նույն չափումն ու ուղղությունը մեկ շաբաթ լուռ են մնում՝ կարգավորելի։ Այս իրադարձությունը պատկանում է ոչ մի աշխատաշրջանի՝ `session_id` և `session_url` արժեքներն են՝ `null`, `link_url` բացում է նախագծի ակնարկը, իսկ `subject_id` անվանում է չափումը, ուղղությունն ու օրը։ Կրում է `metric` (`sessions`, `goal_rate`, `friction_rate`, `js_error_rate`, `lcp_p75`, `inp_p75`, `cls_p75`), `direction`, `day`, `value`, `expected`, `sessions`, `robust_z`, `z_score` և ընթեռնելի `summary` և `hint`։ Այցելուի տվյալներ չկան։ Web Vitals-ի համար `measurements` -ը փոխարինում է `sessions`-ին, իսկ `page` ՝ ամբողջ կայքի համար դատարկ, և `device` (`desktop` կամ `mobil`) հայտնում են՝ որտեղ է կատարվել. `link_url` -ն այդ դեպքում բացում է Web Vitals ներդիրը։
`rage_click`	Զայրացած սեղմման հայտնաբերման պահին
`error_detected`	Հաճախորդային բացառության պահին
`ce`	Ձեր հատուկ իրադարձությունների ընդհանուր բաժանորդագրություն։ Այն չի ներառում վերոնշյալ իրադարձությունները — դրանք սեփական անջատիչներն ունեն։

7. Սխալներ & վիճակի կոդեր

Վիճակ	Իմաստ
`200`	Հաջողություն։
`401`	Բացակայող, սխալ ձևավորված կամ հետ կանչված API բանալի։
`404`	Հարցված նախագիծը կամ աշխատաշրջանը գոյություն չունի կամ չի պատկանում ձեր տարածքին։
`429`	Հաճախականության սահմանը գերազանցված է — այս բանալիով ուղարկում եք րոպեում 60-ից ավելի հարցում։
`403`	Տարածքի պլանը REST API չի ներառում։ Հաղորդագրությունը նշում է պահանջվող և ընթացիկ պլանները։

8. Անվտանգության նշումներ

Միայն ընթերցման բանալիները (mp_ro_) ոչինչ չեն փոխում։ Գրելու բանալիները (mp_rw_) կարող են միայն հաճախորդների ID կցել. ոչ մի բանալի չի կարող ջնջել տվյալներ կամ արտահանել չմշակված ձայնագրության տվյալները։
Յուրաքանչյուր հարցում ինքնաբերաբար սահմանափակվում է բանալու սեփական տարածքով — ուրիշ տարածքի ID փոխանցելով ուրիշի տվյալները տեսնելու եղանակ չկա։
Ցանկացած պահի հետ կանչեք բանալին՝ /api-keysբաժնից. հետկանչն ուժի մեջ է մտնում անմիջապես։
API բանալու հետ վարվեք ինչպես գաղտնաբառի։ Պատահմամբ հանրային շտեմարանում գրանցելու դեպքում անմիջապես հետ կանչեք և նորը ստեղծեք։

Սահմանափակ իրադարձության էջեր (API v1, 14 հոկտեմբերի 2026)

GET /api/v1/sessions/{session_id}/events-ը լռելյայն վերադարձնում է մինչև 100 իրադարձություն։ per_page-ը սահմանեք 1-ից 100 ամբողջ թիվ։ Հետևեք pagination.next_cursor-ին՝ հաջորդ հարցման cursor-ը փոխանցելով անփոփոխ. պահեք նույն աշխատաշրջանն ու տարածքը։ Իրադարձությունները դասավորված են created_at-ով և event_id-ով։ Կուրսորները ստորագրված են և կապված այդ աշխատաշրջանին ու տարածքին։ Ընդհանուր թիվ կամ թվային էջ չի վերադարձվում։

Առկա data զանգվածն ու params քարտեզը մնում են հասանելի։ pagination.returned-ը վերադարձված իրական թիվն է. pagination.has_more-ը նշում է հաջորդ էջի առկայությունը։ Ավարտելիս next_cursor-ը null է։ Պատասխանը սահմանափակված է 524288 բայթով, ուստի էջը կարող է per_page-ից քիչ իրադարձություն ունենալ։ Յուրաքանչյուր իրադարձության համար վերադարձվում է առավելագույնը 128 պարամետրային տող. params_truncated-ը true է, եթե ավելին կա։ Առանձին տեքստային պարամետրերը պահպանում են բազայի 255 նիշի սահմանը։ Կրճատված պարամետրերն այս վերջնակետով հասանելի չեն։ per_page-ը նվազեցնելը չի բարձրացնում պարամետրերի սահմանը։

Էջի անվավեր չափերը, փոփոխված կուրսորները և ուրիշ աշխատաշրջանի/տարածքի կուրսորները վերադարձնում են 400։ Առանձին իրադարձության չափազանց մեծ տվյալները՝ 413։ Առկա հասանելիության ստուգումները ըստ դեպքի շարունակում են վերադարձնել 401, 403, 404 կամ 409։

Սահմանը մնում է րոպեում 60 նույնականացված հարցում՝ յուրաքանչյուր API բանալիի համար։ Սպառվելիս վերադարձվում է 429՝ Retry-After: 60-ով։ Եթե Redis-ը կամ սահմանափակիչն անհասանելի է, հարցումները վերադարձնում են 503՝ Retry-After: 5-ով. առանց սահմանի երբեք չեն ընդունվում։ Հարգեք Retry-After-ը և ավելացրեք պատահական դադար. խիտ ցիկլով մի կրկնեք։ Իրադարձությունների բազայի սխալներն էլ են վերադարձնում 503։ Կուրսորները պատկեր չեն սառեցնում. ավելի հին ժամանակադրոշմով զուգահեռ ներմուծումները կարող են նոր սկանավորում պահանջել։

GET /api/v1/sessions/s_example/events?per_page=25
GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR

/api/v1/native-ը native SDK նախադիտման միայն Dev սերվերային կառավարման ուղի է։ Այն արտադրությունում մնում է անջատված։ Սերվերային Bearer բանալիներին պետք է ընթերցման շրջանակ՝ list/replay-ի, գրելու շրջանակ՝ register/grant/delete/disable-ի համար։ Գործում են native-preview-ի հասանելիության լրացուցիչ ստուգումներ։ Շարժական հավելվածում երբեք մշտական աշխատանքային տարածքի API բանալիներ մի ներդրեք։

Ինչպե՞ս կարող ենք օգնել