# Atribuirea clicurilor pe anunțuri pentru WhatsApp

Dacă rulezi anunțuri Meta sau Google către o pagină de pe propriul tău site web, iar acea pagină are un buton WhatsApp, <span data-t="appName">Your AI Connector</span> îți poate spune din ce clic pe anunț provine fiecare conversație WhatsApp. Introduci un mic script pe site-ul tău. Când un vizitator atinge butonul tău WhatsApp, clic-ul este reținut și asociat cu primul mesaj pe care ți-l trimite. Contactul afișează apoi campania din care provine, iar datele despre clic sunt transmise împreună cu contactul către webhook-uri, API și, dacă dorești, înapoi către Meta.

Acest lucru funcționează pentru orice pagină cu un buton WhatsApp: o pagină de destinație (landing page), o pagină de rezervări, o pagină de prețuri sau un chestionar care se termină cu „Trimite răspunsurile mele pe WhatsApp”.

> Această pagină se referă la anunțurile care trimit oamenii mai întâi pe **site-ul tău**. Dacă anunțurile tale deschid WhatsApp direct (anunțurile Meta de tip „Click to WhatsApp”), acest lucru este acoperit automat, fără un script, în [Atribuirea anunțurilor Click-to-WhatsApp](click-to-whatsapp-attribution.md).

---

## Configurare

1. Mergi la **Setări → Urmărire clicuri pe anunțuri** (grupul Integrări).
2. Dă clic pe **Activează și obține scriptul meu**. Contul tău primește propria cheie de site și un script de un singur rând.
3. Copiază scriptul și lipește-l chiar înainte de eticheta de închidere `</body>` pe fiecare pagină care are un buton WhatsApp:

{% code overflow="wrap" %}
```html
<script src="https://api.youraiconnector.com/v1/ad-visit/YOUR_SITE_KEY.js" async></script>
```
{% endcode %}

4. Opțional: la **Număr WhatsApp**, introdu numărul către care trimit butoanele tale. Doar linkurile către acel număr vor fi urmărite. Lasă câmpul gol pentru a urmări fiecare link WhatsApp de pe site.
5. Alege formularea numărului de interogare (vezi mai jos) și dă clic pe **Salvează**. Nu trebuie să modifici scriptul de pe site-ul tău după o schimbare a setărilor.
6. Testează: deschide pagina ta dintr-un link care conține o etichetă de campanie, de exemplu `https://yoursite.com/?utm_source=test&utm_campaign=setup-check`, atinge propriul buton WhatsApp și trimite mesajul. Deschide acel contact în Chats: panoul de contact afișează **Provenit dintr-un clic pe anunț** împreună cu campania.

Cheia de site este deja inclusă în script. Nu este o parolă, deci este în regulă să fie pe o pagină publică.


---

## Ce face scriptul

- **Când pagina se încarcă**, păstrează ID-urile clicurilor pe anunțuri și etichetele de campanie (parametrii `utm_`) din adresa paginii în stocarea de sesiune a tab-ului din browser, astfel încât acestea să fie disponibile dacă vizitatorul accesează mai întâi o altă pagină. Nu setează niciun cookie, nu încarcă nimic altceva și nu trimite nimic.
- **Când vizitatorul atinge un link WhatsApp** (`wa.me`, `api.whatsapp.com/send` sau `whatsapp://send`), adaugă numărul de interogare la mesaj, înregistrează vizita și permite continuarea atingerii către WhatsApp în mod normal.

Nimic nu este trimis către <span data-t="appName">Your AI Connector</span> înainte de atingere.

---

## Numărul de interogare

Un număr scurt, similar cu referința pe care ți-o oferă un magazin sau o clinică, este adăugat la mesajul WhatsApp al vizitatorului. Acesta este modul în care <span data-t="appName">Your AI Connector</span> știe exact ce clic pe anunț aparține cărei conversații. Un mesaj arată astfel:

```
Hi, I would like to know more.
Enquiry no. 4827
```

- **Formulare:** „Enquiry no.” este valoarea implicită. Poți folosi orice rând de text care sună natural pentru afacerea ta, cum ar fi „Booking ref” sau „Ref”. Fără cifre.
- **Unde:** **Pe propria sa ultimă linie** (implicit) sau **La sfârșitul textului**. Pagina de setări afișează o previzualizare în timp real.
- **Lungime:** 4 cifre, sau 5 când site-ul tău este foarte ocupat.
- **Agentul tău AI nu îl vede niciodată** și nu îl repetă niciodată. Inbox-ul afișează mesajul complet, inclusiv numărul.

Puteți dezactiva numărul de interogare. Potrivirea va funcționa atunci doar pe baza textului mesajului, astfel încât doi vizitatori care trimit exact același text (de exemplu, aceleași răspunsuri la un test) nu pot fi diferențiați, iar unele clicuri nu vor fi potrivite.

---

## propriul cod pentru test sau buton

Dacă pagina dvs. generează singură mesajul WhatsApp (un test care introduce răspunsurile în text sau propriul cod de buton), adăugați `data-manual` la eticheta script:

{% code overflow="wrap" %}
```html
<script src="https://api.youraiconnector.com/v1/ad-visit/YOUR_SITE_KEY.js" data-manual async></script>
```
{% endcode %}

Cu `data-manual`, scriptul nu mai modifică singur linkurile WhatsApp. Propriul cod îl apelează chiar înainte de a deschide WhatsApp, astfel încât fiecare vizită este înregistrată o singură dată:

- `window.ChatAttribution.text(finalText, number)` returnează textul dvs. cu numărul de interogare adăugat și înregistrează vizita. Utilizați textul returnat în linkul dvs. WhatsApp.
- `window.ChatAttribution.link(finalText, number)` face același lucru și returnează un link `wa.me` gata de utilizare cu acel text. Omiteți numărul pentru a-l folosi pe cel de la **Număr WhatsApp** din setări.

{% code overflow="wrap" %}
```html
<script>
  function sendAnswers(answers) {
    var text = "Hi, my answers: " + answers.join(", ");
    if (window.ChatAttribution) {
      window.location.href = window.ChatAttribution.link(text, "+15551234567");
    } else {
      window.location.href = "https://wa.me/15551234567?text=" + encodeURIComponent(text);
    }
  }
</script>
```
{% endcode %}

Ramura `else` menține butonul funcțional dacă scriptul nu s-a încărcat, de exemplu atunci când o extensie de browser îl blochează. Un text care conține deja un număr emis de script nu este niciodată modificat a doua oară.

---

## Ce se înregistrează

La momentul apăsării, înregistrarea vizitei conține:

- ID-urile clicurilor publicitare din adresa paginii, cum ar fi `fbclid` (Meta) și `gclid` (Google)
- cookie-urile `_fbc` și `_fbp`, dacă propriul pixel Meta le-a setat pe site-ul dvs. (scriptul le citește, nu le setează niciodată)
- etichetele de campanie (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`)
- pagina de destinație, pagina de pe care a venit vizitatorul, browserul și textul mesajului
- adresa IP și ora, adăugate de <span data-t="appName">Your AI Connector</span> când vizita este primită

Când o vizită este potrivită, <span data-t="appName">Your AI Connector</span> determină, de asemenea, din acele date, aproximativ unde se afla vizitatorul (orașul și țara, aproximativ, din adresa IP) și ce dispozitiv a folosit (telefon, tabletă sau computer, sistemul de operare și browserul, de exemplu browserul din aplicația Instagram). Locația rămâne goală atunci când nu poate fi determinată, ceea ce este obișnuit în rețelele mobile.

Înregistrările vizitelor sunt păstrate timp de **90 de zile**. Când o vizită este potrivită, o copie a datelor clicurilor sale este stocată în contact și rămâne atașată acestuia până când o ștergeți.

**Notificarea privind confidențialitatea:** scriptul rulează pe site-ul dvs. web, deci notificarea privind confidențialitatea a site-ului dvs. ar trebui să îl menționeze: ce înregistrează (lista de mai sus) și faptul că face acest lucru atunci când un vizitator apasă pe un buton WhatsApp.

---

## Cum funcționează potrivirea

Când sosește primul mesaj al unui contact, <span data-t="appName">Your AI Connector</span> caută o vizită din cele **15 minute** anterioare:

1. **Mai întâi după numărul de interogare.** Un mesaj care conține un număr emis de script este potrivit cu acea vizită.
2. **În caz contrar, după text identic.** Un mesaj cu exact același text ca o vizită este potrivit cu aceasta. Când doi vizitatori diferiți trimit același text în intervalul de timp, niciunul nu este potrivit, în mod intenționat, astfel încât un contact să nu fie niciodată atribuit reclamei greșite.

Un mesaj ulterior care conține numărul de interogare este, de asemenea, potrivit, atâta timp cât contactul nu are încă o potrivire.

Atunci când un contact care are deja o potrivire revine printr-o altă reclamă și trimite un mesaj care conține un număr de solicitare mai nou, acel clic este păstrat ca **cel mai recent clic** al contactului. Prima potrivire rămâne neschimbată.

- **Primul clic, pentru raportarea ta:** contactul continuă să arate de unde a provenit inițial lead-ul. Acest lucru nu se schimbă niciodată.
- **Cel mai recent clic, pentru Meta:** evenimentele trimise către Meta folosesc cel mai nou clic, deoarece Meta atribuie creditul reclamei care a adus persoana înapoi și doar în fereastra sa de atribuire. Raportarea unui clic vechi ar atribui creditul reclamei greșite sau niciuneia.
- Cel mai recent clic este preluat doar dintr-un număr de solicitare, niciodată doar din textul de potrivire, iar o vizită mai veche nu o înlocuiește niciodată pe una mai nouă.

Limite:

- **Prima potrivire nu este niciodată suprascrisă.** Clicurile mai noi sunt stocate în cel mai recent clic.
- **Doar WhatsApp:** canalele WhatsApp Business API și WhatsApp Web.
- **15 minute:** un vizitator care apasă butonul, dar trimite mesajul mult mai târziu, nu este potrivit.
- **Doar de acum înainte:** contactele de dinainte de instalarea scriptului nu au nicio potrivire.

---

## Unde îl poți vedea

- **Panou de contact:** **A venit dintr-un clic pe anunț** cu campania sau sursa și data primului clic. Treceți cu mouse-ul pentru detalii: campania, **Anunțul** (`utm_content`) și **Setul de anunțuri** (`utm_term`), **Locația** aproximativă și **Dispozitivul**, fiecare doar atunci când este cunoscut, plus aceleași informații pentru cel mai recent clic, dacă există unul. Etichetele de campanie care nu au fost completate niciodată (o atingere de previzualizare a anunțului trimite șablonul etichetei în loc de nume) sunt omise. O vizită contează ca un clic pe anunț doar atunci când pagina a fost deschisă dintr-un link de anunț (un ID de clic Meta sau Google, sau etichete de campanie). Oricine a ajuns pe pagină prin altă metodă, de exemplu din căutarea Google, tastând adresa sau dând clic prin site-ul dvs., va afișa **A venit de pe site-ul dvs.** cu sursa de proveniență, cum ar fi **Căutare Google** sau **Vizită pe site, fără referrer înregistrat** când browserul nu a furnizat informația.
- **Pagină de contact:** aceeași linie se află sub numele contactului în **Contacte**, astfel încât să o vedeți imediat, și pe telefon. Treceți cu mouse-ul sau atingeți pentru detalii.
- **Activitate:** cronologia contactului începe cu **A atins butonul WhatsApp după un anunț** (sau **pe site-ul dvs.**) la momentul clicului, înainte de primul mesaj. Panoul de contact al chat-ului afișează aceeași linie sub **Activitate**.
- **Webhook-uri:** `contact.ad_attribution` în [webhook-urile etichetelor de agent](webhooks.md#contact-tags-updated-webhook) și în fiecare eveniment de abonare la webhook care conține un contact.
- **API:** `ad_attribution` în lista de contacte și `adAttribution` pe un singur contact, în secțiunea Contacte din referința API.
- **Instrumente MCP:** același obiect pe fiecare contact pe care îl returnează.

Valoarea este `null` atunci când contactul nu are nicio potrivire. Câmpurile de mai jos descriu primul clic. Când un clic ulterior a fost potrivit, `latest` îl stochează cu aceleași câmpuri; acesta este absent până atunci.

| Câmp | Ce reprezintă |
|---|---|
| `visit_at` | Când vizitatorul a atins butonul WhatsApp. |
| `matched_at` | Când vizita a fost potrivită cu contactul. |
| `match_method` | `reference` (potrivit prin numărul de solicitare) sau `text` (potrivit prin textul identic al mesajului). |
| `reference` | Numărul de solicitare sau `null` când a fost dezactivat. |
| `fbc` / `fbp` | Clicul Meta și cookie-urile de browser de la propriul pixel Meta, dacă sunt prezente. |
| `fbclid` | ID-ul de clic al anunțului Meta din adresa paginii. |
| `gclid` / `gbraid` / `wbraid` | ID-urile de clic ale anunțurilor Google din adresa paginii. |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term` | Etichetele de campanie din adresa paginii. |
| `landing_url` | Pagina pe care a aterizat vizitatorul. |
| `referrer` | Pagina de pe care a venit vizitatorul. |
| `client_ip` | Adresa IP a vizitatorului. |
| `user_agent` | Browserul vizitatorului. |
| `geo_country` / `geo_region` / `geo_city` / `geo_timezone` | Locația aproximativă din adresa IP: codul de țară din două litere, codul regiunii, orașul și fusul orar. Absent când este necunoscut. |
| `device_type` / `device_os` / `device_browser` | Dispozitivul din browser: `mobile`, `tablet` sau `desktop`, sistemul de operare cu versiunea sa (cum ar fi `iOS 18.3`) și browserul (cum ar fi `Safari` sau `Instagram in-app`). Absent când este necunoscut. |
| `site_key` | Cheia site-ului scriptului care a înregistrat vizita. |
| `visit_id` | ID-ul înregistrării vizitei. |
| `latest` | Cel mai recent clic potrivit după primul, cu aceleași câmpuri. Folosit pentru evenimentele trimise către Meta. Absent când nu există niciunul. |

---

## Trimite rezultatele către Meta (opțional)

Poți permite <span data-t="appName">Your AI Connector</span> să raporteze rezultatele înapoi în contul tău de anunțuri Meta, astfel încât Meta să învețe ce anunțuri aduc clienți potențiali și vânzări reale și să le optimizeze. Aceasta utilizează propriile tale detalii Meta Conversions API.

1. În Meta Events Manager, găsește ID-ul pixelului tău (numit și set de date) la secțiunea Surse de date și creează un token de acces în Setări, Conversions API, **Generare token de acces**.
2. În **Setări → Urmărire clicuri anunțuri**, la secțiunea **Trimite rezultatele către Meta (opțional)**, introdu **ID-ul pixelului / setului de date** și **Tokenul de acces**. Apasă pe **Salvează detaliile Meta**.
3. Opțional: verifică conexiunea. În Meta Events Manager, deschide pixelul și mergi la fila **Testare evenimente**, copiază codul de test afișat acolo, lipește-l în secțiunea **Trimite un eveniment de test** și apasă pe **Trimite eveniment de test**. Linia de sub buton va afișa „Meta a primit 1 eveniment de test” (verifică în secțiunea Testare evenimente din Meta) sau va arăta motivul pentru care Meta a refuzat evenimentul, de exemplu un token greșit. Codul este utilizat doar pentru acel test și nu este salvat niciodată.
4. Deschide editorul de agenți, mergi la fila **Etichete** și deschide o etichetă. La secțiunea **Trimite către Meta**, alege evenimentul: **Lead**, **Contact**, **Programare**, **Achiziție** sau un nume personalizat. Opțional, adaugă o valoare și o monedă.

De atunci încolo, ori de câte ori acea etichetă este aplicată unui contact (de către AI, manual, prin API sau printr-o automatizare), <span data-t="appName">Your AI Connector</span> trimite evenimentul către Meta cu datele celui mai nou clic al contactului (`fbc`, `fbp`, adresa IP, browserul, pagina de destinație, din cel mai recent clic dacă există unul, altfel din primul) plus telefonul, e-mailul și numele acestuia, criptate (hashed), astfel încât Meta să le poată asocia cu reclama. Un contact fără potrivire trimite în continuare evenimentul, doar cu telefonul, e-mailul și numele criptate.

- **Evenimentele live sunt întotdeauna luate în calcul:** un cod de eveniment de test nu este stocat niciodată împreună cu detaliile tale Meta, astfel încât evenimentele trimise de etichetele și automatizările tale ajung întotdeauna la datele tale reale din Meta, niciodată în fila Testare evenimente.
- **Fără numărare dublă:** fiecare eveniment are un ID fix format din ID-ul contactului și numele etichetei. Dacă CRM-ul tău trimite același eveniment către Meta cu același ID, Meta îl păstrează doar o dată.
- **Fereastra de atribuire Meta:** Meta creditează un eveniment unui anunț doar în interiorul ferestrei sale de atribuire, care este de 7 zile de la clic în mod implicit. O afacere care se încheie săptămâni mai târziu nu va fi contorizată de la sine, așa că trimite și un eveniment anterior, de exemplu o etichetă pentru consultația rezervată sau plătită.

---

## Trimite conversii din automatizări

Un tag trimite evenimentul său atunci când este aplicat. Când rezultatul are loc în altă parte, cum ar fi închiderea unei oportunități (deal) în CRM-ul tău sau programarea unei consultații, folosește acțiunea **Trimite conversia către Meta** într-o automatizare. Aceasta raportează un eveniment către setul tău de date Meta prin Conversions API, astfel încât Meta să îți optimizeze reclamele pe baza rezultatelor reale, nu doar pe baza mesajelor.

Aceasta utilizează aceleași detalii Meta ca și tag-urile: **Pixel / ID set de date** și **Token de acces** din **Setări → Urmărire clicuri reclame**. Fără acestea, pasul eșuează cu mesajul „Meta nu este conectat”.

**Câmpurile**

| Câmp | Ce face |
|---|---|
| **Nume eveniment** | Obligatoriu. **Achiziție**, **Programare**, **Lead** sau propriul tău nume. Numele propriu folosește litere, cifre, spații și caractere de subliniere, începe cu o literă și are maximum 40 de caractere. |
| **Valoare** și **Monedă** | Suma conversiei, cum ar fi valoarea afacerii. Moneda este un cod de 3 litere și este setată implicit la EUR. Valoarea este trimisă doar atunci când o completezi. |
| **Contact** | Opțional. Contactul căruia îi aparține conversia. |
| **E-mail**, **Telefon**, **Prenume**, **Nume** | Detaliile persoanei. Completează-le atunci când persoana nu este un contact sau pentru a adăuga informații suplimentare la cele existente pentru contact. |
| **ID-ul tău pentru persoană** | Un ID pentru persoană din propriul tău sistem, cum ar fi un ID de CRM. |
| **ID eveniment** | ID-ul pe care Meta îl folosește pentru a număra evenimentul o singură dată. Vezi mai jos. |
| **Ora evenimentului** | Momentul în care a avut loc conversia, sub formă de secunde Unix sau dată. Cu cel mult 7 zile în urmă. Lasă gol pentru a utiliza momentul în care rulează pasul. |
| **URL pagină** | Pagina la care este legată conversia, dacă există. |
| **Cod eveniment de test** | Doar pentru o rulare de test: codul din fila Testare evenimente din Meta. Un eveniment trimis cu acesta apare în Testare evenimente și nu este contorizat pentru anunțurile tale. Lasă gol pentru evenimente live. |

Completează cel puțin unul dintre câmpurile **Contact**, **Email** sau **Telefon**. Persoana nu trebuie să fie neapărat un contact: o oportunitate HubSpot care ajunge în stadiul „Closed Won” poate trimite un eveniment de tip **Purchase** cu valoarea oportunității și adresa de e-mail a cumpărătorului.

Când alegi un **Contact**, sunt folosite numărul de telefon, adresa de e-mail și numele acestuia. Dacă persoana provine dintr-un clic pe o reclamă pe care scriptul l-a identificat, detaliile clicului sunt și ele transmise, ceea ce ajută Meta să potrivească evenimentul cu reclama. Adresa de e-mail, numărul de telefon și numele sunt criptate (hashed) înainte de a fi trimise. ID-ul clic-ului, adresa IP și browserul sunt trimise conform cerințelor Meta.

**ID eveniment și numărarea dublă**

Meta numără o singură dată evenimentele cu același nume și același ID de eveniment. Folosește un ID fix, cum ar fi ID-ul oportunității, atunci când un alt instrument raportează aceeași conversie sau când automatizarea ar putea rula de două ori pentru aceasta. Lasă câmpul gol pentru a genera un ID nou la fiecare rulare, astfel încât fiecare rulare să fie contorizată.

**Cum diferă de evenimentele de tip tag**

Evenimentul **Trimite către Meta** al unui tag se declanșează o singură dată per contact pentru acel tag (cel mult o dată la 30 de zile). Această acțiune trimite datele de fiecare dată când rulează. ID-ul evenimentului este cel care previne numărarea dublă a unei conversii.

**Exemplu: o oportunitate închisă și o consultație programată**

1. Pornește o automatizare care rulează atunci când o afacere este câștigată: un declanșator de tip **App event** pentru evenimentul de afacere din CRM-ul tău, cu o **Condition** astfel încât să continue doar afacerile câștigate. HubSpot trimite evenimente de etapă a afacerii doar către aplicațiile pentru dezvoltatori, așa că pentru HubSpot folosește un declanșator de tip **Schedule** cu o căutare HubSpot pentru afacerile care au ajuns în stadiul „Closed Won” de la ultima rulare și un **Loop** peste acestea.
2. Adaugă **Send conversion to Meta**. Setează **Event name** la **Purchase**, **Value** la valoarea afacerii (insereaz-o cu butonul **+**) și **Currency** la moneda ta. Introdu adresa de e-mail a cumpărătorului în **Email** și ID-ul afacerii în **Event ID**, astfel încât aceeași afacere să nu fie numărată niciodată de două ori.
3. Pentru o consultație programată, pornește o a doua automatizare cu declanșatorul **Appointment booked** și adaugă **Send conversion to Meta** cu **Event name** setat la **Schedule** și contactul din declanșator în **Contact**. Dacă dorești, adaugă un al doilea pas **Send conversion to Meta** care trimite un **Purchase** cu o valoare fixă, cum ar fi prețul consultației.

Poți trimite o conversie și prin API cu `POST https://api.youraiconnector.com/v1/ad-attribution/meta-event`. Acesta preia aceleași câmpuri în format snake case: `event_name`, `value`, `currency`, `contact_id`, `email`, `phone`, `first_name`, `last_name`, `external_id`, `event_id`, `event_time`, `event_source_url` și `test_event_code`.

---

## Întrebări frecvente

**Funcționează acest lucru dacă anunțul meu deschide WhatsApp direct?**
Acele anunțuri nu trec prin site-ul tău, deci scriptul nu rulează niciodată. Meta trimite detaliile anunțului cu primul mesaj, vezi [Atribuirea anunțurilor Click-to-WhatsApp](click-to-whatsapp-attribution.md).

**Scriptul încetinește site-ul meu sau setează cookie-uri?**
Se încarcă în fundal (`async`), nu setează niciun cookie și nu încarcă nimic altceva. Trimite ceva doar atunci când un vizitator atinge un buton WhatsApp.

**Pot urmări Google Ads la fel ca anunțurile Meta?**
Da. ID-urile de clic Google (`gclid`, `gbraid`, `wbraid`) și orice etichete de campanie sunt înregistrate și afișate pe contact. Trimiterea rezultatelor înapoi este disponibilă doar pentru Meta.

**De ce un contact nu a primit o potrivire?**
Cele mai frecvente motive: mesajul a sosit la mai mult de 15 minute după atingere, numărul de interogare a fost eliminat din mesaj, numărul de interogare este dezactivat și un alt vizitator a trimis același text, sau pagina nu are scriptul.

**Site-ul meu conține linkuri către două numere WhatsApp. Pot urmări doar unul?**
Da. Introdu acel număr sub **Număr WhatsApp** în setări. Lasă câmpul gol pentru a urmări fiecare link WhatsApp.

**Pot modifica textul ulterior?**
Da. Modificările se aplică imediat pe site-ul tău; nu este nevoie să lipești din nou scriptul.