API ọha & igodo API

1. Nchịkọta

API MousePlayer na-ahapụ gị ịdọrọ data n'oghere ọrụ gị banye na bọọdụ nchịkwa nke gị, ụlọ nkwakọba data ma ọ bụ ngwa ime. Ewezuga itinye ID ndị ahịa na nnọkọ (identify, chọrọ igodo nwere ikike ide, lee Oke igodo), ọ bụ naanị maka ịgụ: a pụghị ịgbanwe ma ọ bụ hichapụ data site na API.

• URL ntọala: https://www.mouseplayer.com/api/v1/
• Nzaghachi niile bụ JSON.
• A na-eji igodo API nyochaa arịrịọ ọ bụla, a na-etinyekwa ya na oke oghere ọrụ nke igodo ahụ bụ na-akpaghị aka — igodo sitere n'otu oghere ọrụ enweghị ike ịhụ data oghere ọrụ ọzọ, ọbụna site na mberede.
• Ndekọ ịkpọgharị nnọkọ zuru ezu (mmegharị òké, onyonyo DOM) adịghị na API. Ị na-enweta metadata nnọkọ, nlele ibe, ihe omume nke gị na ngalaba — nke zuru iji wuo akụkọ na bọọdụ nchịkwa n'ebufeghị data ịkpọgharị mbụ gburugburu.

2. Nyocha njirimara

Mepụta ma jikwaa igodo API gị n'okpuru Igodo API n'ime menu akaụntụ gị (/api-keys). Naanị ndị nwe oghere ọrụ na ndị nchịkwa nwere ike ịmepụta ma ọ bụ kagbuo igodo.

Ziga igodo ahụ dịka token Bearer n'ime nkụnye Authorization nke arịrịọ ọ bụla:

Igodo na-adịghị, nke usoro ya ezighi ezi ma ọ bụ nke akagbuola na-enweta nzaghachi 401 :

Ihe atụmatụ chọrọ

REST API bụ akụkụ atụmatụ Business na Enterprise . A na-ewere atụmatụ site n'aka onye nwe oghere ọrụ, ya mere ndị otu a kpọrọ òkù na-eketa ya. Nyocha ahụ na-arụ na arịrịọ ọ bụla, ọ bụghị naanị mgbe a na-emepụta igodo — ọ bụrụ na e belata ọkwa oghere ọrụ, igodo ndị dị adị na-akwụsị ịrụ ọrụ wee weghachite 403.

Oke igodo

Igodo ọ bụla na-ebu oke ya n'ime nganiihu nke ya, ka ị nwee ike ịmata ihe igodo na-eme site n'ile ya anya — n'ime .env, n'ime tiketi, n'ime terminal.

3. Oke arịrịọ

Igodo API ọ bụla nwere oke arịrịọ 60 kwa nkeji, nke a na-agụ n'ime windo na-agagharị. Ozugbo ị gafere ya, arịrịọ na-enweta nzaghachi 429 ruo mgbe windo ahụ sachara:

4. Ebe njedebe

GET/api/v1/projects

Na-edepụta ọrụ ngo ọ bụla (webụsaịtị a na-enyocha) dị n'oghere ọrụ gị.

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

Na-edepụta nnọkọ ndị ọbịa e dekọrọ maka ọrụ ngo, nke kacha ọhụrụ na mbụ. E kewara n'ibe.

GET/api/v1/sessions/{session_id}

Metadata maka otu nnọkọ, tinyere nlele ibe ya. E kpachapụrụ anya wepụ data ịkpọgharị zuru ezu — jiri ihe ọkpụkpọ bọọdụ nchịkwa maka nke ahụ.

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

Ihe omume nke gị a kpalitere n'oge nnọkọ (otu ihe omume ị na-eziga site na mp('event', ...)), tinyere paramita ha.

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

Na-edepụta ngalaba ndị ọbịa akọwara maka ọrụ ngo (ngalaba ọrụ ngo kpọmkwem na ndị oghere ọrụ dum).

5. Itinye ID onye ahịa site na sava gị

Ihe nchọgharị anaghị amakarị onye nọ ebe ahụ. N'ime ngwaahịa B2B, a na-ekpebi njirimara mgbe nbanye gachara — n'akụkụ sava gị. N'ime ụlọ ahịa, a na-ekpebi ya site na nkwenye iwu. Ebe njedebe a bụ maka kpọmkwem oge ahụ.

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 ahụ na-apụta mgbe ahụ na ndepụta nnọkọ, a pụrụ ịchọ ya ebe ahụ, webhook session_identified na-arụkwa ọrụ — nke bụ otu o si erute CRM gị.

6. Webhook: inyocha mbinye aka

A na-ahazi webhook n'otu ọrụ ngo n'okpuru Njikọ, ebe ị na-ahụkwa ihe nzuzo mbinye aka. Nnyefe ọ bụla na-ebu nkụnye ndị a:

Mbinye aka bụ HMAC-SHA256 nke timestamp + "." + raw body, jiri ihe nzuzo mbinye aka ọrụ ngo gị dịka igodo.

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

Nnyefe na mgbalị ọzọ

A na-anwale nnyefe dara ọzọ mgbe nkeji 1, nkeji 5, nkeji 15, awa 1 na awa 6gachara, a hapụzie ya. 4xx Nzaghachi ndị na-abụghị 408 na 429 bụ ndị a naghị anwale ọzọ — ha na-ekwu "ọ bụghị otú a", ọ bụghị "ọ bụghị ugbu a". Zaa 2xx ngwa ngwa ma rụọ ọrụ mgbe nke ahụ gasịrị; nnyefe na-agwụ oge mgbe sekọnd 10 gachara.

Ihe omume dị

7. Njehie & koodu ọnọdụ

8. Ndetu nchekwa

• Igodo ịgụ naanị (mp_ro_) enweghị ike ịgbanwe ihe ọ bụla. Igodo ide (mp_rw_) nwere ike naanị itinye ID ndị ahịa; ọ dịghị igodo nwere ike ihichapụ data ma ọ bụ ibupụ data ịkpọgharị mbụ.
• A na-etinye arịrịọ ọ bụla na oke oghere ọrụ igodo ahụ n'onwe ya na-akpaghị aka — ụzọ ịnyefe ID oghere ọrụ ọzọ wee hụ data onye ọzọ adịghị.
• Kagbuo igodo mgbe ọ bụla site na /api-keys; nkagbu na-amalite ịrụ ọrụ ozugbo.
• Were igodo API gị dịka okwuntughe. Ọ bụrụ na i tinye otu na mberede na ebe nchekwa koodu ọha, kagbuo ya ozugbo ma mepụta nke ọhụrụ.