- Pinterest Conversions API trimite evenimente de conversie de pe un server către contul tău de reclame Pinterest, alături de Pinterest Tag din browser.
- Pinterest numește o achiziție finalizată checkout; trimite-o cu valoarea, moneda, id-ul comenzii și articolele.
- Pinterest potrivește evenimentele pe baza datelor clientului cu hash, a adresei IP împreună cu user agent-ul și a click id-ului epik.
- Pinterest deduplică un eveniment Tag și un eveniment API cu același event_id și același nume de eveniment și îl păstrează pe primul; ROASaurus trimite toate cele cinci evenimente de shopping în acest mod.
- Testează mai întâi cu modul de test: Pinterest ține evenimentele de test în afara raportării și a optimizării.
Pinterest Conversions API este modul server-to-server prin care Pinterest primește evenimente de conversie. Magazinul tău sau un instrument precum ROASaurus trimite evenimente, cum ar fi achizițiile, direct către contul tău de reclame Pinterest, în loc să se bazeze doar pe Pinterest Tag din browserul cumpărătorului. Pinterest folosește datele pentru raportarea conversiilor, optimizarea campaniilor și targetare.
Acest ghid acoperă API-ul v5 și evenimentele pe care le acceptă, click id-ul epik, cum primesc hash datele clientului, cum funcționează deduplicarea cu Pinterest Tag, cum testezi și cum configurezi totul pe Shopify.
Ce este Pinterest Conversions API?
Pinterest Tag este un script din browserul cumpărătorului. Conversions API face aceeași treabă de pe un server. În versiunea 5 a API-ului, trimiți evenimentele către endpoint-ul de evenimente al contului tău de reclame, autorizat cu un token de acces pentru conversii pe care îl creezi în Pinterest Ads Manager. Fiecare eveniment spune unde a avut loc: pentru un magazin online, sursa acțiunii este web.
Pinterest le cere agenților de publicitate care folosesc și Tag-ul să evite numărarea unei conversii de două ori, transmițând un event_id cu fiecare eveniment. Cere și ca evenimentele să fie trimise în timp real sau cel mult la o oră după ce au loc.
Pe Shopify, o conexiune de pe server are un avantaj clar: achizițiile provin chiar din comandă. Shopify raportează fiecare comandă plătită către ROASaurus prin webhook, iar ROASaurus o trimite către Pinterest la scurt timp după plată, indiferent dacă Tag-ul s-a declanșat sau nu în browser. Ghidul despre tracking-ul server-side pe Shopify explică ideea în detaliu.
- Rulează în browserul cumpărătorului
- Poate fi oprit de ad blockere și de erori de script
- Raportează vizitele pe pagini pe măsură ce au loc
- Rulează pe un server
- Trimite achizițiile din datele comenzii tale
- Are nevoie cel puțin de un email sau de o adresă IP cu user agent
Ce evenimente acceptă Pinterest Conversions API?
Pinterest are o listă fixă de nume de evenimente standard, scrise cu litere mici și cu liniuțe de subliniere, precum page_visit, add_to_cart și checkout. Poți defini și până la 15 tipuri de evenimente personalizate pentru fiecare agent de publicitate. ROASaurus asociază astfel cele cinci evenimente de cumpărare din Shopify:
| Acțiunea cumpărătorului | Numele evenimentului în API | Deduplicat cu Tag în ROASaurus |
|---|---|---|
| Vizualizează o pagină | page_visit | Da |
| Vizualizează un produs | view_content | Da |
| Adaugă în coș | add_to_cart | Da |
| Începe checkout-ul | initiate_checkout | Da |
| Finalizează o comandă | checkout | Da |
Numele poate crea confuzie. Checkout-ul din Pinterest este achiziția finalizată, nu începutul checkout-ului. Începutul checkout-ului este un eveniment separat, initiate_checkout.
Pentru evenimentul de checkout, Pinterest recomandă să trimiți valoarea, moneda, id-ul comenzii, id-urile de conținut și numărul de articole. ROASaurus le trimite pe toate cinci, plus cantitatea și prețul fiecărui articol. Pinterest cere valoarea înainte de taxe și livrare. Pe Shopify, ROASaurus trimite exact asta: totalul comenzii minus taxele și livrarea, de pe server și din tagul din browser. Când platforma unui magazin online nu raportează separat taxele și livrarea, ROASaurus trimite totalul comenzii.
Cum potrivește Pinterest un eveniment cu o persoană?
Fiecare eveniment conține date despre utilizator. Pinterest cere cel puțin unul dintre trei lucruri: o adresă de email cu hash, un id publicitar mobil cu hash sau adresa IP împreună cu user agent-ul. Un magazin online nu are id publicitar, deci are nevoie de email sau de adresa IP și user agent. ROASaurus omite un eveniment care nu are niciunul dintre ele, în loc să trimită unul pe care Pinterest nu îl poate folosi.
| Câmp | Ce conține | Trimis ca |
|---|---|---|
| em | Adresa de email | Hash SHA-256 al emailului scris cu litere mici |
| ph | Număr de telefon | Hash SHA-256 |
| fn, ln, ct, st, zp, country | Prenume, nume de familie, oraș, stat, cod poștal și țară | Hash SHA-256 |
| external_id | Id-ul de client Shopify sau id-ul de vizitator ROASaurus | Hash SHA-256 |
| client_ip_address | Adresa IP a cumpărătorului | Valoare în clar |
| client_user_agent | User agent-ul browserului cumpărătorului | Valoare în clar |
| click_id | Valoarea epik dintr-un click pe o reclamă Pinterest | Valoare în clar |
Click id-ul epik
Click id-ul Pinterest poate veni din două locuri: un parametru epik din URL-ul paginii de destinație sau cookie-ul _epik de pe domeniul tău. Ghidul API al Pinterest recomandă transmiterea valorii cookie-ului _epik, pentru că funcționează și când parametrul din URL lipsește sau a fost eliminat, ceea ce oferă o acoperire mai bună.
ROASaurus le citește pe amândouă în vitrina ta, folosind parametrul din URL când un click nou aduce unul și cookie-ul în rest. Salvează click id-ul împreună cu vizitatorul și îl trimite în câmpul click_id al fiecărui eveniment de pe server, inclusiv al achiziției. Vizitele cu un epik sunt numărate ca vizite Pinterest în rapoartele de atribuire ROASaurus.
POST https://api.pinterest.com/v5/ad_accounts/549755885175/events
{
"data": [{
"event_name": "checkout",
"action_source": "web",
"event_time": 1793016000,
"event_id": "order-5512345678901",
"event_source_url": "https://example-store.com/checkouts/…/thank-you",
"user_data": {
"em": ["a3f1…9c2e"],
"ph": ["7b40…11d8"],
"external_id": ["e05c…4a7f"],
"client_ip_address": "203.0.113.24",
"client_user_agent": "Mozilla/5.0 (iPhone; …)",
"click_id": "dj0yJnU9…"
},
"custom_data": {
"currency": "USD",
"value": "84",
"order_id": "5512345678901",
"content_ids": ["44123456789"],
"contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
"num_items": 2
}
}]
}Cum funcționează deduplicarea cu Pinterest Tag?
Dacă Tag-ul și API-ul raportează amândouă o achiziție, Pinterest primește două evenimente pentru o singură comandă. Ca să le trateze ca pe unul, are nevoie de același id în ambele părți: id-ul evenimentului din Tag trebuie să se potrivească cu event_id din evenimentul de pe server. Pinterest îl păstrează pe primul eveniment primit și elimină duplicatele care sosesc în 48 de ore.
ROASaurus construiește id-ul achiziției din id-ul comenzii Shopify. Achiziția din comanda 5512345678901 are event id-ul order-5512345678901, atât în Tag-ul care se declanșează în checkout, cât și în evenimentul de pe server.
Toate cele cinci evenimente sunt deduplicate
Fiecare eveniment de shopping din ROASaurus are un singur event id, folosit de Tag-ul din browser și de evenimentul de pe server. Tag-ul folosește numele proprii ale Pinterest pentru aceleași evenimente: pagevisit, viewcontent, addtocart, initiatecheckout și checkout, care corespund cu page_visit, view_content, add_to_cart, initiate_checkout și checkout din API. Așadar, când rulează ambele, Pinterest păstrează o singură copie a fiecărei vizite pe pagină, vizualizări de produs, adăugări în coș, începuturi de checkout și achiziții.
Poți rula asta în două moduri:
- Tag și Conversions API împreună. Tag-ul adaugă semnale din browser, serverul completează ce ratează Tag-ul, iar Pinterest îmbină copiile.
- Rulează API-ul fără Tag. Lasă gol Tag ID sau dezactivează Also load the browser tag. Fiecare eveniment este atunci trimis o singură dată, doar de pe server.
Articolul de ajutor despre numărarea dublă acoperă aceleași verificări pentru celelalte platforme de publicitate.
Cum testezi Pinterest Conversions API?
API-ul are un indicator de test. Cererile trimise cu test=true ajung într-un sandbox: Pinterest le tratează ca date de test și nu le folosește pentru raportare sau optimizare.
- Activează modul de test
În ROASaurus, editează pixelul Pinterest din Tracking & platforms și bifează Test mode (events show under Test events, max 20). Fiecare eveniment de pe server este apoi trimis cu test=true. Pinterest procesează cel mult 20 de evenimente de test pe lot.
- Plasează o comandă de test
Vizitează-ți magazinul, vezi un produs, adaugă-l în coș și finalizează o comandă.
- Citește rezultatul
Deschide Event log. Pinterest poate răspunde cu HTTP 200 chiar dacă un eveniment dintr-o cerere a eșuat, așa că ROASaurus verifică statusul fiecărui eveniment și arată acolo eșecurile.
- Dezactivează modul de test
Debifează modul de test, ca evenimentele să conteze în raportare și în optimizare.
- Verifică Events Overview
În Pinterest Ads Manager, deschide pagina Events Overview. Ea arată evenimentele care sosesc și conversiile deduplicate. Pinterest recomandă să urmărești un Event Quality Score Good.
Cum configurezi Pinterest Conversions API pe Shopify cu ROASaurus
Ai nevoie de un magazin Shopify cu aplicația ROASaurus și de acces la Pinterest Ads Manager. Pagina integrării Pinterest listează fiecare câmp pe care îl trimite ROASaurus.
- Conectează-ți magazinul Shopify
Mergi la Add a store › Shopify, fă click pe Install app și activează încorporarea aplicației ROASaurus în editorul de teme. Aceasta captează epik și cookie-ul _epik pe fiecare pagină. Ghidul de configurare Shopify arată fiecare pas.
- Creează un token de acces pentru conversii
În Pinterest Ads Manager, mergi la Conversions și creează un token de acces pentru conversii. Notează ID-ul contului tău de reclame.
- Adaugă pixelul Pinterest în ROASaurus
Mergi la Tracking & platforms, fă click pe Add pixel pe cardul Pinterest și completează Ad account ID și Conversion access token.
- Adaugă Tag ID-ul tău
Pentru deduplicarea cu Tag-ul, completează Pinterest Tag ID și lasă bifat Also load the browser tag. Fără un Tag ID, ROASaurus trimite doar evenimente de pe server și nu încarcă Tag-ul.
- Adaugă pixelul de checkout
În Shopify admin › Settings › Customer events, adaugă un pixel personalizat numit ROASaurus și lipește fragmentul de pe pagina ta Tracking & platforms. El declanșează evenimentul checkout al Tag-ului în checkout-ul Shopify, cu id-ul comenzii ca event_id.
- Alege evenimentele de pe server, apoi testează
Alege evenimentele de pe server pe care le vrei și testează cu modul de test înainte să treci în producție.
Cu Respect visitor consent activat, ceea ce este implicit, ROASaurus respectă alegerea cumpărătorului din bannerul de cookie-uri al Shopify. Când un cumpărător refuză cookie-urile de marketing, ROASaurus nu încarcă Pinterest Tag pentru el, nu setează un id de vizitator, deci click-urile lui nu îi sunt asociate, și nu trimite către Pinterest evenimentele lui de navigare. Comanda lui plătită este totuși trimisă de pe server către Conversions API, cu datele comenzii cu hash și cu adresa IP și user agent-ul comenzii, dar fără click id. Ghidul despre consimțământ și confidențialitate explică ce este stocat și trimis.
Conectează-ți contul de reclame Pinterest la Setup › Ad spend, iar ROASaurus preia cheltuielile campaniilor în fiecare oră, ca să vezi ROAS-ul Pinterest și profitul după reclame în analiza profitului. Ghidul TikTok Events API acoperă aceeași configurare pentru TikTok, unde fiecare eveniment care merge pe ambele căi este deduplicat.
Surse
- Pinterest Developers: Track conversion events in the API
- Pinterest Business help: The Pinterest Conversions API
- Pinterest Developers: Track conversions with Pinterest Tag