API Cyhoeddus & Allweddi API

1. Trosolwg

Mae API MousePlayer yn gadael i chi dynnu data o’ch gweithle i’ch dangosfyrddau, warws data neu offer mewnol eich hun. Ar wahân i atodi IDs cwsmeriaid at sesiynau (identify, angen allwedd â chwmpas ysgrifennu, gweler Cwmpas Allweddi), mae’n ddarllen yn unig: ni ellir addasu na dileu data drwy’r API.

• URL Sylfaenol: https://www.mouseplayer.com/api/v1/
• JSON yw pob ymateb.
• Dilysir pob cais gydag allwedd API a’i gwmpasu’n awtomatig i’r gweithle y mae’r allwedd yn perthyn iddo — ni all allwedd o un gweithle byth weld data gweithle arall, hyd yn oed ar ddamwain.
• Nid yw’r recordiad ailchwarae sesiwn llawn (symudiadau llygoden, cipluniau DOM) yn cael ei ddarparu drwy’r API. Rydych yn cael metadata sesiwn, golygon tudalen, digwyddiadau personol a segmentau — digon i adeiladu adroddiadau a dangosfyrddau heb gludo llwyth crai’r ailchwarae o gwmpas.

2. Dilysu

Crëwch a rheolwch eich allweddi API o dan Allweddi API yn newislen eich cyfrif (/api-keys). Dim ond perchnogion a gweinyddwyr gweithleoedd sy’n gallu creu neu ddirymu allweddi.

Anfonwch yr allwedd fel tocyn Bearer ym mhennyn Authorization pob cais:

Mae allweddi coll, camffurfiedig neu wedi’u dirymu yn cael ymateb 401:

Gofyniad Cynllun

Mae’r REST API yn rhan o gynlluniau Business ac Enterprise. Cymerir y cynllun oddi wrth berchennog y gweithle, felly mae aelodau tîm a wahoddwyd yn ei etifeddu. Mae’r gwiriad yn rhedeg ar bob cais, nid dim ond pan grëir allwedd — os caiff gweithle ei israddio, mae allweddi presennol yn peidio â gweithio ac yn dychwelyd 403.

Cwmpas Allweddi

Mae pob allwedd yn cario ei chwmpas yn ei rhagddodiad ei hun, felly gallwch ddweud beth mae allwedd yn ei wneud drwy edrych arni — mewn .env, mewn tocyn, mewn terfynell.

3. Terfynau Cyfradd

Mae pob allwedd API wedi’i chyfyngu i 60 cais y funud, wedi’u tracio ar ffenestr dreigl. Unwaith y byddwch yn mynd dros hynny, mae ceisiadau’n cael ymateb 429 nes bod y ffenestr yn clirio:

4. Pwyntiau Terfyn

GET/api/v1/projects

Yn rhestru pob prosiect (gwefan wedi’i thracio) yn eich gweithle.

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

Yn rhestru sesiynau ymwelwyr a recordiwyd ar gyfer prosiect, y diweddaraf yn gyntaf. Wedi’u rhannu’n dudalennau.

GET/api/v1/sessions/{session_id}

Metadata un sesiwn, ynghyd â’i golygon tudalen. Yn fwriadol nid yw’n cynnwys llwyth ailchwarae llawn — defnyddiwch Chwaraewr y dangosfwrdd ar gyfer hynny.

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

Digwyddiadau personol a sbardunwyd yn ystod sesiwn (yr un digwyddiadau rydych yn eu hanfon gyda mp('event', ...)), gan gynnwys eu paramedrau.

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

Yn rhestru’r segmentau ymwelwyr a ddiffiniwyd ar gyfer prosiect (segmentau penodol i’r prosiect ac ar draws y gweithle).

5. Atodi ID Cwsmer o’ch Pen Ôl

Yn aml nid yw’r porwr yn gwybod pwy sy’n eistedd yno. Mewn cynnyrch B2B pennir yr hunaniaeth ar ôl mewngofnodi — yn eich pen ôl. Mewn siop fe’i pennir gyda’r cadarnhad archeb. Mae’r pwynt terfyn hwn ar gyfer yr union foment honno.

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}}

Yna mae’r ID yn ymddangos yn y rhestr sesiynau, gellir chwilio amdano yno, ac mae’r webhook session_identified yn tanio — dyna sut mae’n cyrraedd eich CRM.

6. Webhooks: Dilysu’r Llofnod

Ffurfweddir webhooks fesul prosiect o dan Integreiddiadau, lle cewch hefyd y gyfrinach lofnodi. Mae pob danfoniad yn cynnwys y penynnau hyn:

Mae’r llofnod yn HMAC-SHA256 dros timestamp + "." + raw body, gyda chyfrinach lofnodi eich prosiect fel allwedd.

// 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');

Danfon ac Ailgeisiadau

Ailgeisir danfoniad aflwyddiannus ar ôl 1 munud, 5 munud, 15 munud, 1 awr a 6 awr, yna rhoddir y gorau iddo. 4xx yw’r ymatebion, ac eithrio 408 a 429, nad ydynt yn cael eu hailgeisio — maent yn dweud "nid fel hyn", nid "nid ar hyn o bryd". Ymatebwch gyda 2xx yn gyflym a gwnewch y gwaith wedyn; daw amser danfon i ben ar ôl 10 eiliad.

Digwyddiadau Sydd ar Gael

7. Gwallau & Codau Statws

8. Nodiadau Diogelwch

• Ni all allweddi darllen yn unig (mp_ro_) newid dim. Dim ond atodi IDs cwsmeriaid y gall allweddi ysgrifennu (mp_rw_) ei wneud; ni all unrhyw allwedd ddileu data nac allforio data ailchwarae crai.
• Caiff pob cais ei gwmpasu’n awtomatig i weithle’r allwedd ei hun — nid oes ffordd i drosglwyddo ID gweithle gwahanol a gweld data rhywun arall.
• Dirymwch allwedd ar unrhyw adeg o /api-keys; daw dirymu i rym ar unwaith.
• Triniwch eich allwedd API fel cyfrinair. Os gwnewch ei chynnwys ar ddamwain mewn commit i ystorfa gyhoeddus, dirymwch hi ar unwaith a chreu un newydd.