ChatGPT Ads Conversions API: seadistamise juhend

ChatGPT Ads Conversions API lühivastus

Saada sündmused oma serverist aadressile https://bzr.openai.com/v1/events?pid=PIXEL-ID, kasutades Authorization Bearer päises ainult serverile loodud Conversions API võtit. Päringu events-massiiv sisaldab iga sündmuse kordumatut id-väärtust, toetatud tüüpi, millisekundites ajatemplit, tegevuse allikat, veebisündmuse korral lähte-URL-i ja sündmusele sobivat data-objekti.

Conversions API ei püüa reklaamiklikiga saabunud oppref-väärtust automaatselt. Salvesta see maandumislehelt esimese osapoole seosena ja saada algne väärtus konversioonisündmusega muutmata kujul. Kui kasutad paralleelselt OpenAI Pixelit, anna samale konversioonile mõlemas kanalis sama Pixel ID, sündmuse nimi ja sündmuse ID.

Alusta validate_only kontrolliga, testi üks sündmus korraga ja vaata seejärel hiljutiste sündmuste vaates server_to_server kanalit. Alles pärast tehnilist kinnitust loo sündmuse seadistus, seo see kampaaniaga ning hinda tulemusi Ads Manageri või Insightsi raportis.

Millal valida CAPI, Pixel või mõlemad?

Brauseri Pixel sobib lehevaatamiste, sisu vaatamise ja muude brauseris nähtavate tegevuste mõõtmiseks. CAPI sobib eriti hästi sündmustele, mille tõesus selgub serveris: edukalt loodud tellimus, kinnitatud makse, CRM-i salvestatud müügivihje, broneeritud aeg või käivitunud prooviperiood.

Ainult serveripoolne lahendus võib töötada ka ilma Pixeli brauserikoodita, kuid vajab endiselt Ads Manageris loodud Pixel ID-d. Sel juhul vastutab sinu süsteem kliki viite säilitamise, sündmuse sisu, kordussaadetiste kontrolli ja kasutaja nõusoleku loogika eest.

Pixel ja CAPI koos annavad rohkem kontrollpunkte, kuid ainult siis, kui deduplitseerimine on õigesti tehtud. Ära saada kahest kanalist kahte erineva ID-ga “sama” ostu. Kui server kinnitab lõpliku tulemuse, kasuta serverit tõeallikana ning hoia brauserisündmus abistava või sama ID-ga deduplitseeritava signaalina.

Mida on enne arendust vaja?

Esmalt loo või vali Ads Manageris õige veebipõhine konversiooniallikas. OpenAI API eristab andmeallika id-väärtust ja pixel_id-väärtust: sündmuse saatmise URL-is kasutatakse Pixel ID-d, sündmuse seadistuse loomisel aga allika ID-d. Kirjuta mõlemad eraldi integratsiooni konfiguratsiooni, et neid ei vahetataks.

Loo Conversions API võti ning paiguta see serveri saladuste hoidlasse. See võti ei ole sama mis Advertiser API võti, mida kasutatakse kampaaniate ja seadistuste haldamiseks api.ads.openai.com aadressil. CAPI sündmused liiguvad bzr.openai.com aadressile oma võtmega.

Defineeri enne koodi üks põhisündmus ja selle tõend. Näiteks lead_created tekib alles pärast seda, kui backend on kontakti salvestanud; order_created pärast kinnitatud tellimust; appointment_scheduled pärast päriselt broneeritud aega. Nupu klikk või vormi avamine ei ole sama mis kinnitatud tulemus.

õige konversiooniallika Pixel ID sündmuste saatmiseks
eraldi Conversions API võti serveri saladuste hoidlas
üks dokumenteeritud põhisündmus ja selle serveripoolne käivitustingimus
püsiv tellimuse, müügivihje või muu tegevuse ID
oppref-i säilitamise reegel ja nõusoleku loogika
testkeskkond, logide redaktsioon ning ligipääs hiljutiste sündmuste kontrollile

Soovituslik serveripoolne andmevoog

Maandumisleht võtab vastu OpenAI reklaamiklikiga saabunud oppref-väärtuse. Nõusoleku ja sinu privaatsusreeglite järgi seotakse see esimese osapoole seansi, ostukorvi või lead-kirjega. UTM-parameetrid võib samal ajal salvestada GA4 ja CRM-i jaoks, kuid need ei asenda oppref-i.

Kui ärisündmus on backendis kinnitatud, koostab server OpenAI sündmuse. ID tuleb sinu püsivast ärikirjest, ajatempel kirjeldab tegelikku sündmust ning data-objekt sisaldab ainult valitud sündmuse jaoks vajalikke välju. Seejärel lisab saatmisteenus Bearer-võtme, saadab päringu ja salvestab tehnilise vastuse ilma saladust või tooreid isikuandmeid logimata.

Eralda sündmuse loomine saatmisest järjekorra või taustatööga. Kasutaja ostu või vormi õnnestumine ei peaks sõltuma mõõtmispartneri hetkevastusest. Järjekord võimaldab ohutult uuesti proovida, jälgida ebaõnnestumisi ja säilitada sama sündmuse ID.

reklaamiklik → oppref salvestatakse lubatud esimese osapoole seosena
veeb või rakendus → ärisündmus kinnitatakse serveris
backend → luuakse üks püsiva ID-ga sündmus
järjekord → sündmus saadetakse CAPI-sse sama ID-ga ka korduskatse korral
kontroll → hiljutine sündmus, sündmuse seadistus ja kampaania seos vaadatakse üle
raport → Ads Manageri tulemusi võrreldakse GA4, CRM-i ja päris müügiga

CAPI võtme turvaline kasutamine

Conversions API võti on saladus. Ära lisa seda veebilehe JavaScripti, Google Tag Manageri veebikonteinerisse, dataLayer’isse, mobiilirakenduse paketti, avalikku hoidlassse ega kliendile nähtavasse keskkonnamuutujasse. Server loeb võtme ainult käitusajal saladuste hoidlast.

Piira ligipääs võtmele väikseima vajaliku teenuse ja töötajate ringiga. Erista test- ja tootmiskeskkonna konfiguratsioon, roteeri võti kontrollitud protsessiga ning veendu, et vealogid ei prindi Authorization päist ega kogu päringu toorandmeid.

Kui võtme lekkimist ei saa välistada, lõpeta selle kasutamine ja asenda see. Ära peida võtit lihtsalt uue muutujanime või kodeeringu taha: brauserisse jõudnud saladus ei ole enam saladus.

Sündmuse päringu anatoomia

Päringu ülemisel tasemel on events-massiiv ning soovi korral validate_only ja integration_source. OpenAI dokumentatsiooni järgi võib ühes päringus olla kuni 1000 sündmust. Kui üks sündmus ebaõnnestub, ebaõnnestub kogu pakk, mistõttu on käivitamisel väiksemad pakid lihtsamad diagnoosida.

Iga sündmuse id peab olema kordumatu ja korduskatsetel püsiv. type on toetatud standardsündmus või kohandatud sündmus, timestamp_ms on sündmuse Unix-aeg millisekundites ning action_source kirjeldab allikat. Veebisündmusel lisa source_url. data-objekti kuju peab vastama sündmuse tüübile.

Ära mõtle summale kui komakohaga tekstile. OpenAI sündmused kasutavad raha puhul täisarvu valuuta väikseimas ühikus: 79,90 eurot tähendab amount 7990 ja currency EUR. Kontrolli sama reeglit kõigi e-poe, tellimuse ja tellimuspõhiste väärtuste juures.

Näide: kinnitatud ostu saatmine

E-poes loo order_created alles pärast serveri kinnitust. Sündmuse id võib olla näiteks order_12345, data type on contents, amount on täisarvuna valuuta väikseimas ühikus ning currency kasutab sobivat valuutakoodi. source_url näitab teekonda, kus tegevus toimus, mitte suvalist avalehte.

Kui ostule eelnes OpenAI reklaamiklik, lisa salvestatud oppref sündmuse tasemel muutmata kujul. Kui sama ost saadeti ka Pixeliga, peab Pixeli event_id olema täpselt sama mis CAPI id. Ära loo API korduskatsel uut juhuslikku ID-d.

Kaupade detailid lisa ainult siis, kui need on mõõtmise eesmärgi jaoks vajalikud ja vastavad dokumenteeritud väljale. Turvaline miinimum on sageli parem kui kogu tellimuse, kliendiprofiili või vaba tekstiga märkuste saatmine.

Näide: müügivihje ja broneering

Teenuseettevõttes sobib lead_created siis, kui päring on serveris salvestatud ja vastab sinu müügivihje definitsioonile. appointment_scheduled sobib hetkele, mil aeg on päriselt broneeritud. Pelk kontaktilehe avamine, telefonilingi klikk või vormi saatmise nupp ei tõesta kumbagi.

Kasuta sündmuse ID-na CRM-i kontakti, päringu või broneeringu püsivat tehnilist ID-d, mitte inimese e-posti aadressi. Kui sama vormivastus jõuab webhooki kaudu mitu korda, peab integratsioon leidma olemasoleva sündmuse ja säilitama sama ID.

Kui tahad mõõta nii lead_created kui hilisemat appointment_scheduled sündmust, saada need eraldi ID-de ja selgete ajahetkedega. Kampaania peamiseks konversiooniks vali sündmus, mis on piisavalt sagedane, kuid esindab päris ärilist väärtust.

oppref ja obref ei ole sama asi

oppref on OpenAI reklaamiklikiga maandumislehele jõudev kliki viide. CAPI ei korja seda ise. Püüa väärtus saabumisel, säilita see muutmata ja lisa hilisemale serverisündmusele. Katkenud suunamine, domeenivahetus või ostukorvi uus seanss võib selle seose kaotada, mistõttu tuleb kogu teekond läbi testida.

obref on Pixeli loodud läbipaistmatu brauseriviide, mille saab CAPI sündmuse user-objektis muutmata edasi anda. OpenAI kirjeldab selle allikana __obref küpsist. Kogu ja edasta obref ainult siis, kui kasutaja mõõtmisnõusolek seda lubab, ning lõpeta kogumine või saatmine nõusoleku tagasivõtmisel.

UTM-id kirjeldavad sinu kampaaniataksonoomiat GA4-s ja CRM-is. Neid tasub säilitada, kuid ükski UTM ei asenda oppref-i ega obref-i. Hea integratsioon hoiab kolm kihti eraldi: OpenAI omistamisviide, brauseri viide ja sinu analüütika parameetrid.

Valikulised kasutajaandmed ja turvaline räsimine

CAPI user-objekt võib sisaldada sobitamiseks räsitud e-posti, telefoni, välise ID, ees- ja perekonnanime väärtusi ning teatud tooreid kontekstiandmeid, nagu IP-aadress ja user agent. Need väljad on valikulised. Saada ainult andmed, mille jaoks sul on õiguslik alus, selge eesmärk ja dokumenteeritud säilitamisreegel.

Räsimine algab normaliseerimisest. OpenAI juhendi järgi e-post kärbitakse ja muudetakse väiketähtedeks; telefon normaliseeritakse riigikoodiga; väline ID kärbitakse, kuid selle tähesuurus säilib; nimed muudetakse väiketähtedeks ning neist eemaldatakse tühikud ja ASCII kirjavahemärgid. Seejärel kasuta SHA-256 tulemust väiketähtedega kuueteistkümnendkujul.

Ära räsi juba räsitud väärtust uuesti ja ära prindi toorväärtust debug-logi. Räsimine ei muuda isikuandmete töötlemist automaatselt anonüümseks. Kui vajalikkus on kaheldav, alusta oppref-ist, sündmuse andmetest ja minimaalsest tehnilisest kontekstist ning laienda alles põhjendatud mõõtmisvajaduse korral.

Kuidas Pixel ja CAPI topeltsündmust väldivad?

OpenAI deduplitseerib sama konversiooni Pixel ID, sündmuse nime ja sündmuse ID kombinatsiooni järgi. Pixeli options-objekti event_id peab seega võrduma serverisündmuse id-väärtusega. Standardse ostu puhul peab mõlemas kanalis olema ka sama sündmus order_created.

Esimesena saabunud sobiv sündmus jääb arvesse. See tähendab, et deduplitseerimine ei ole meetod kahe erineva sisuga sündmuse “parima versiooni” hilisemaks valimiseks. Hoia põhiandmed kooskõlas ning otsusta, milline süsteem loob ID ja milline kinnitab sündmuse tõesuse.

Kohandatud sündmuse puhul peab kattuma ka kohandatud sündmuse nimi. Deduplitseerimine ei paranda valesti nimetatud sündmust, erinevat Pixel ID-d ega olukorda, kus sama tellimus saab iga lehevärskendusega uue ID.

Testimine validate_only abil

Lisa esimesele päringule validate_only: true. OpenAI kontrollib sündmuse vormingut, kuid ei salvesta seda. Seetõttu ei ilmu valideerimispäring hiljutiste sündmuste vaatesse. Testi eraldi korrektset sündmust ja teadlikult vigast varianti, et veakäsitlus oleks tõendatud.

Pärast skeemi kinnitamist saada kontrollitud testkirje ilma validate_only režiimita. Kasuta testtellimust või testi-ID-d, mida saad hiljem logides, CRM-is ja Ads Manageris üheselt tuvastada. Veendu, et sündmuse kanal on server_to_server ja et nimi, ajatempel ning allikas on oodatud.

Ära testi tootmises päris kliendiandmetega ainult selleks, et näha rohelist vastust. Testandmed, eraldi keskkond ja logide redaktsioon vähendavad nii privaatsus- kui ka aruandlusriski.

Korduskatsed, idempotentsus ja pakivead

Võrgukatkestus või 5xx vastus ei tohiks kaotada kinnitatud ostu. Hoia sündmus järjekorras, kasuta eksponentsiaalset viivitust ja säilita igal katsel sama id. Ära tõlgenda teadmata vastust automaatselt ebaõnnestumiseks ega loo uut sündmust uue ID-ga.

Erista püsivad valideerimisvead ajutistest teenusevigadest. Puuduv nõutud väli, sobimatu sündmuse tüüp või vigane summa vajab andmete parandamist; ajutine võrguviga võib vajada korduskatset. Salvesta vastuse kood, sündmuse sisemine ID ja katsete arv, kuid mitte saladust ega tarbetuid kasutajaandmeid.

Kuna ühe vigase sündmuse tõttu võib ebaõnnestuda terve kuni 1000 sündmusega pakk, kasuta alguses väikseid pakke. Suure mahu korral lisa võimalus pakk pooleks jagada ja probleemne sündmus karantiini suunata.

Sündmuse seadistus ja kampaania seos

Tehniliselt vastu võetud CAPI sündmus ei ole veel kampaania konversioon. Ads Manageris või Advertiser API kaudu tuleb luua sündmuse seadistus, mis valib andmeallikast konkreetse standard- või kohandatud sündmuse. OpenAI API seadistus nõuab nime, sündmuse tüüpi, 30-päevast atribuutimisakent ja täpselt üht allika ID-d.

Seejärel seosta õige konversioon kampaaniaga. Kontrolli seda enne uut testklikki või kampaania käivitust. Event setting valib sündmuse, kuid ei saada seda; CAPI saadab sündmuse, kuid ei seo seda automaatselt suvalise kampaaniaga.

Kasuta nimetustes ärilist tähendust ja keskkonda, näiteks “EE demo broneeritud – production”. Väldi viit eri seadistust nimega “Lead”, sest hiljem on raske aru saada, milline allikas ja sündmus kampaania otsuseid mõjutab.

Kuidas sündmust pärast käivitust kontrollida?

Hiljutiste sündmuste kontroll näitab OpenAI dokumentatsiooni järgi ligikaudu viimase 15 minuti sündmuste valimit ning eristab serveripoolset kanalit server_to_server. See sobib integratsiooni kontrolliks, mitte ajalooliseks tulemusraportiks.

Kampaania konversioone ja efektiivsust vaata Ads Manageri või Insightsi raportist. OpenAI märgib, et konversiooniandmete töötlemine on päevapõhine ja värske tulemus võib vajada vähemalt päeva. Ära järelda samal minutil nullist, et mõõtmine ei tööta.

Hoia oma seirepaneelil vähemalt edukate, valideerimisveaga, ajutise veaga ja järjekorda jäänud sündmuste arv. Võrdle iga päev OpenAI vastuvõttu serveri kinnitatud ostude või müügivihjetega ning uuri järske erinevusi.

Privaatsus ja nõusolek Eestis

Serveripoolne saatmine ei vabasta läbipaistvuse, andmeminimeerimise ega nõusoleku kohustusest. Kaardista, millised väljad liiguvad OpenAI-le, mille alusel neid töödeldakse, kui kaua seoseid säilitatakse ja kuidas kasutaja saab oma valikut muuta.

Eriti oluline on siduda obref-i kogumine mõõtmisnõusolekuga ning lõpetada see tagasivõtmisel. oppref-i, UTM-ide, IP-aadressi ja räsitud tunnuste käsitlus peab vastama sinu privaatsusteatele, CMP loogikale ja andmekaitseanalüüsile.

Ära saada vabasid tekstivälju, märkmeid, eriliigilisi isikuandmeid ega muid detaile, mida reklaami tulemusmõõtmine ei vaja. Tehniline võimalus ei ole automaatne põhjendus.

Avaldamiseelne kontrollnimekiri

Enne tootmisse lülitamist salvesta testprotokoll koos sündmuse ID, aja, keskkonna, nõusoleku oleku ja kontrolli tulemusega. Vastutaja peab suutma ühe sündmuse teekonda reklaamiklikist serverikirje ja OpenAI vastuseni jälitada.

Pixel ID ja allika ID on eristatud ning pärinevad õigest Ads Manageri kontost
Conversions API võti on ainult serveri saladuste hoidlas ja logidest eemaldatud
põhisündmus tekib serveris alles kinnitatud ärilise tegevuse järel
id on püsiv, kordumatu ja jääb korduskatsetel samaks
summa on valuuta väikseimas ühikus täisarv ning currency on kaasas
oppref säilib läbi suunamiste ja seda ei muudeta
obref-i ning valikuliste kasutajaandmete jaoks on sobiv nõusolek ja minimaalne väljade valik
validate_only test läbib ning päris test on näha server_to_server kanaliga
Pixel+CAPI korral kattuvad Pixel ID, sündmuse nimi ja sündmuse ID
sündmuse seadistus on loodud ja õige kampaaniaga seotud
veakäsitlus eristab valideerimisviga ajutisest veast ega loo uut ID-d
seire võrdleb CAPI vastuvõttu serveri päris tellimuste või müügivihjetega

Levinud vead ja nende lahendus

401 või 403 vastuse korral kontrolli, kas kasutad õiget Conversions API võtit, õiges Authorization Bearer päises ja serverist. Advertiser API võti ei ole CAPI võtme asendus. 400-seeria valideerimisvea puhul vaata nõutud välju, sündmuse tüüpi, data-objekti ja ajatemplivormingut.

Kui sündmus võetakse vastu, kuid omistamist ei teki, kontrolli oppref-i teekonda, sündmuse seadistust, kampaania seost ja testkliki aega. Kui ost ilmub kaks korda, kontrolli Pixel ID, sündmuse nime ning Pixeli event_id ja CAPI id täpset võrdsust.

Kui terve pakk ebaõnnestub, jaga see väiksemaks ja isoleeri vigane sündmus. Kui hiljutiste sündmuste vaade on tühi, veendu, et validate_only on eemaldatud, õige Pixel ID on URL-is ja päring ei jäänud sinu järjekorda.

Kala Ruudus ehitab mõõtmise reklaamiklikist müügini

Kala Ruudus aitab valida ChatGPT Ads põhisündmuse, kaardistada oppref-i ja nõusoleku teekonna, koostada CAPI andmelepingu ning siduda Pixeli, serverisündmuse, GA4 ja CRM-i üheks kontrollitavaks mõõtmisloogikaks.

Tulemuseks on sündmuste sõnastik, võtmete ja keskkondade turvamudel, arenduse spetsifikatsioon, testprotokoll, deduplitseerimise kontroll ning kampaania seos. Vajaduse korral aitame ka Advertiser API automatiseerimise ja Insightsi raportiga.

Saada meile veebiaadress, kasutatav e-poe, vormi või CRM-i platvorm ning kirjelda, milline tegevus on sinu jaoks päris müügitulemus. Vastame stardiplaaniga, mis ütleb, kas vajad ainult CAPI-t, Pixelit või mõlemat ning millised lüngad tuleb enne kampaania eelarve suurendamist sulgeda.

Korduma kippuvad küsimused

Mis on ChatGPT Ads Conversions API?

See on OpenAI serveripoolne liides, millega saadad kinnitatud ostu, müügivihje, broneeringu või muu toetatud sündmuse oma serverist reklaami mõõtmissüsteemi. Päring kasutab Pixel ID-d ja ainult serveris hoitavat Conversions API võtit.

Kas Conversions API kasutamiseks on OpenAI Pixelit vaja?

Brauseri Pixeli paigaldus ei ole server-only lahenduse jaoks kohustuslik, kuid sündmuste saatmiseks on vaja Ads Manageris loodud Pixel ID-d. Pixeli ja CAPI kooskasutamisel tuleb sama konversioon deduplitseerida ühise ID-ga.

Kuhu Conversions API võti salvestada?

Ainult serveri saladuste hoidlasse või samaväärsesse turvalisse konfiguratsiooni. Võtit ei tohi panna brauseri JavaScripti, GTM-i veebikonteinerisse, dataLayer’isse, mobiilirakendusse, avalikku hoidlasse ega logidesse.

Mis vahe on oppref- ja obref-väärtusel?

oppref on reklaamiklikiga maandumislehele jõudev viide, mille server peab algsel kujul säilitama ja sündmusega saatma. obref on Pixeli __obref küpsisest pärit läbipaistmatu brauseriviide, mida võib nõusoleku korral edastada sündmuse user-objektis.

Kuidas vältida Pixeli ja CAPI topeltkonversiooni?

Kasuta sama konversiooni jaoks sama Pixel ID-d, sündmuse nime ja sündmuse ID-d. Pixeli event_id peab võrduma CAPI id-väärtusega ning korduskatse ei tohi luua uut ID-d.

Kuidas CAPI sündmust enne avaldamist testida?

Alusta validate_only: true päringuga, mis kontrollib skeemi sündmust salvestamata. Seejärel saada üks päris testkirje ja kontrolli hiljutiste sündmuste vaates server_to_server kanalit, õiget nime, ID-d ning andmeallikat.

Loe edasi

Kontrollitud allikad

Artikli tootefaktid kontrolliti 1. oktoobril 2026.

Oluline

Platvormi võimalused, saadavus ja hinnastus võivad muutuda. Kontrollime kampaania planeerimisel alati konto hetkeolukorda ning OpenAI ametlikku dokumentatsiooni.

ChatGPT Ads Conversions API: serveripoolse mõõtmise juhend