# Atrybucja kliknięć reklam dla WhatsApp

Jeśli kierujesz reklamy Meta lub Google na stronę w swojej witrynie, a ta strona zawiera przycisk WhatsApp, <span data-t="appName">DM Champ</span> może poinformować Cię, z którego kliknięcia w reklamę pochodzi dana konwersacja w WhatsApp. Wystarczy wkleić na swojej stronie jeden krótki skrypt. Gdy odwiedzający kliknie przycisk WhatsApp, kliknięcie zostanie zapamiętane i przypisane do pierwszej wiadomości, którą do Ciebie wyśle. Następnie przy kontakcie wyświetli się kampania, z której pochodzi, a dane o kliknięciu powędrują wraz z kontaktem do webhooków, API oraz, jeśli chcesz, z powrotem do Meta.

Działa to na każdej stronie z przyciskiem WhatsApp: stronie docelowej (landing page), stronie rezerwacji, stronie z cennikiem lub quizie, który kończy się przyciskiem „Wyślij moje odpowiedzi przez WhatsApp”.

> Ta strona dotyczy reklam, które najpierw kierują użytkowników na **Twoją witrynę**. Jeśli Twoje reklamy otwierają WhatsApp bezpośrednio (reklamy Meta „Click to WhatsApp”), jest to obsługiwane automatycznie, bez użycia skryptu, w sekcji [Atrybucja reklam Click-to-WhatsApp](click-to-whatsapp-attribution.md).

---

## Konfiguracja

1. Przejdź do **Ustawienia → Śledzenie kliknięć reklam** (grupa Integracje).
2. Kliknij **Włącz i pobierz mój skrypt**. Twoje konto otrzyma własny klucz witryny oraz jednowierszowy skrypt.
3. Skopiuj skrypt i wklej go tuż przed tagiem zamykającym `</body>` na każdej stronie, która zawiera przycisk WhatsApp:

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

4. Opcjonalnie: w polu **Numer WhatsApp** wpisz numer, do którego prowadzą Twoje przyciski. Wtedy śledzone będą tylko linki do tego numeru. Pozostaw to pole puste, aby śledzić każdy link WhatsApp w witrynie.
5. Wybierz brzmienie numeru zapytania (patrz poniżej) i kliknij **Zapisz**. Po zmianie ustawień nie musisz zmieniać skryptu na swojej stronie.
6. Przetestuj to: otwórz swoją stronę z linku zawierającego tag kampanii, na przykład `https://yoursite.com/?utm_source=test&utm_campaign=setup-check`, kliknij własny przycisk WhatsApp i wyślij wiadomość. Otwórz ten kontakt w czatach: panel kontaktu pokaże **Pochodzi z kliknięcia w reklamę** wraz z nazwą kampanii.

Klucz witryny znajduje się już wewnątrz skryptu. Nie jest to hasło, więc bezpiecznie można go używać na publicznej stronie.

::: master-only
**Agencje:** każde konto klienta ma własny klucz witryny i skrypt, dzięki czemu witryna każdego klienta raportuje dane do własnego konta. Możesz ukryć sekcję dla klienta za pomocą widoczności menu, tak jak każdą inną sekcję ustawień.
:::

---

## Co robi skrypt

- **Podczas ładowania strony**, zapisuje identyfikatory kliknięć reklam i tagi kampanii (parametry `utm_`) z adresu strony w pamięci sesji karty przeglądarki, dzięki czemu pozostają one dostępne, jeśli odwiedzający najpierw przejrzy inną stronę. Nie ustawia żadnych plików cookie, niczego innego nie ładuje i niczego nie wysyła.
- **Gdy odwiedzający kliknie link WhatsApp** (`wa.me`, `api.whatsapp.com/send` lub `whatsapp://send`), dodaje numer zapytania do wiadomości, rejestruje wizytę i pozwala na kontynuowanie kliknięcia do WhatsApp w normalny sposób.

Przed kliknięciem nic nie jest wysyłane do <span data-t="appName">DM Champ</span>.

---

## Numer zapytania

Krótki numer, podobny do numeru referencyjnego nadawanego przez sklep lub przychodnię, jest dodawany do wiadomości WhatsApp odwiedzającego. Dzięki niemu <span data-t="appName">DM Champ</span> wie dokładnie, które kliknięcie w reklamę należy do której konwersacji. Wiadomość wygląda tak:

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

- **Brzmienie:** Domyślnie jest to „Enquiry no.”. Możesz użyć dowolnego tekstu jednowierszowego, który brzmi naturalnie dla Twojej firmy, na przykład „Booking ref” lub „Ref”. Bez cyfr.
- **Miejsce:** **W osobnej ostatniej linii** (domyślnie) lub **Na końcu tekstu**. Strona ustawień pokazuje podgląd na żywo.
- **Długość:** 4 cyfry lub 5, gdy Twoja witryna jest bardzo obciążona ruchem.
- **Twój agent AI nigdy go nie widzi** i nigdy go nie powtarza. Skrzynka odbiorcza pokazuje pełną wiadomość, włącznie z numerem.

Możesz wyłączyć numer zapytania. Dopasowywanie będzie wtedy działać tylko na podstawie treści wiadomości, więc dwóch odwiedzających, którzy wyślą dokładnie ten sam tekst (na przykład te same odpowiedzi w quizie), nie będzie mogło zostać rozróżnionych, a niektóre kliknięcia nie zostaną dopasowane.

---

## Twój własny kod quizu lub przycisku

Jeśli Twoja strona sama tworzy wiadomość WhatsApp (quiz, który umieszcza odpowiedzi w tekście, lub Twój własny kod przycisku), dodaj `data-manual` do tagu skryptu:

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

Dzięki `data-manual` skrypt nie zmienia już samodzielnie linków WhatsApp. Twój własny kod wywołuje go tuż przed otwarciem WhatsApp, więc każda wizyta jest rejestrowana tylko raz:

- `window.ChatAttribution.text(finalText, number)` zwraca Twój tekst z dodanym numerem zapytania i rejestruje wizytę. Użyj zwróconego tekstu w swoim linku WhatsApp.
- `window.ChatAttribution.link(finalText, number)` robi to samo i zwraca gotowy link `wa.me` z tym tekstem. Pomiń numer, aby użyć tego znajdującego się w ustawieniach w sekcji **Numer WhatsApp**.

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

Gałąź `else` sprawia, że przycisk działa, nawet jeśli skrypt się nie załadował, na przykład gdy blokuje go rozszerzenie przeglądarki. Tekst, który już zawiera numer nadany przez skrypt, nigdy nie jest zmieniany po raz drugi.

---

## Co jest rejestrowane

W momencie kliknięcia rekord wizyty zawiera:

- identyfikatory kliknięć reklam w adresie strony, takie jak `fbclid` (Meta) i `gclid` (Google)
- pliki cookie `_fbc` i `_fbp`, jeśli Twój własny piksel Meta ustawił je w Twojej witrynie (skrypt je odczytuje, nigdy ich nie ustawia)
- tagi kampanii (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`)
- stronę docelową, stronę, z której przyszedł odwiedzający, przeglądarkę oraz treść wiadomości
- adres IP i czas, dodane przez <span data-t="appName">DM Champ</span> w momencie dotarcia wizyty

Rekordy wizyt są przechowywane przez **90 dni**. Gdy wizyta zostanie dopasowana, kopia danych o kliknięciu jest zapisywana w kontakcie i pozostaje przy nim, dopóki jej nie usuniesz.

**Twoja informacja o prywatności:** skrypt działa na Twojej stronie internetowej, więc informacja o prywatności Twojej witryny powinna o nim wspominać: co rejestruje (lista powyżej) oraz że robi to, gdy odwiedzający kliknie przycisk WhatsApp.

---

## Jak działa dopasowywanie

Gdy dotrze pierwsza wiadomość od kontaktu, <span data-t="appName">DM Champ</span> szuka wizyty z ostatnich **15 minut**:

1. **Najpierw według numeru zapytania.** Wiadomość zawierająca numer nadany przez skrypt jest dopasowywana do tej wizyty.
2. **W przeciwnym razie według identycznego tekstu.** Wiadomość o dokładnie takiej samej treści jak wizyta jest do niej dopasowywana. Jeśli dwóch różnych odwiedzających wysłało ten sam tekst w tym samym oknie czasowym, żaden z nich nie zostanie dopasowany – jest to celowe działanie, aby kontakt nigdy nie został błędnie przypisany do niewłaściwej reklamy.

Późniejsza wiadomość, która zawiera numer zapytania, również zostanie dopasowana, o ile kontakt nie ma jeszcze przypisanego dopasowania.

Limity:

- **Pierwsze dopasowanie wygrywa.** Gdy kontakt zostanie dopasowany, informacja ta nigdy nie jest nadpisywana.
- **Tylko WhatsApp:** kanały WhatsApp Business API oraz WhatsApp Web.
- **15 minut:** odwiedzający, który kliknie przycisk, ale wyśle wiadomość znacznie później, nie zostanie dopasowany.
- **Tylko przyszłe zdarzenia:** kontakty sprzed zainstalowania skryptu nie mają dopasowania.

---

## Gdzie to zobaczysz

- **Panel kontaktu:** **Pochodzi z kliknięcia w reklamę** wraz z kampanią lub źródłem oraz datą. Najedź kursorem, aby zobaczyć szczegóły.
- **Webhooki:** `contact.ad_attribution` w [webhookach tagów agenta](webhooks.md#contact-tags-updated-webhook) oraz w każdym zdarzeniu subskrypcji webhooka, które zawiera kontakt.
- **API:** `ad_attribution` na liście kontaktów oraz `adAttribution` przy pojedynczym kontakcie, w sekcji Kontakty w dokumentacji API.
- **Narzędzia MCP:** ten sam obiekt przy każdym zwracanym kontakcie.

Wartość wynosi `null`, gdy kontakt nie ma dopasowania.

| Pole | Co to jest |
|---|---|
| `visit_at` | Kiedy odwiedzający kliknął przycisk WhatsApp. |
| `matched_at` | Kiedy wizyta została dopasowana do kontaktu. |
| `match_method` | `reference` (dopasowano po numerze zapytania) lub `text` (dopasowano po identycznym tekście wiadomości). |
| `reference` | Numer zapytania lub `null`, gdy był wyłączony. |
| `fbc` / `fbp` | Kliknięcie Meta i pliki cookie przeglądarki z Twojego własnego piksela Meta, jeśli są obecne. |
| `fbclid` | Identyfikator kliknięcia reklamy Meta z adresu strony. |
| `gclid` / `gbraid` / `wbraid` | Identyfikatory kliknięć reklam Google z adresu strony. |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term` | Tagi kampanii z adresu strony. |
| `landing_url` | Strona, na którą trafił odwiedzający. |
| `referrer` | Strona, z której przyszedł odwiedzający. |
| `client_ip` | Adres IP odwiedzającego. |
| `user_agent` | Przeglądarka odwiedzającego. |
| `site_key` | Klucz witryny skryptu, który zarejestrował wizytę. |
| `visit_id` | Identyfikator rekordu wizyty. |

---

## Wysyłaj wyniki do Meta (opcjonalnie)

Możesz pozwolić <span data-t="appName">DM Champ</span> na raportowanie wyników do Twojego konta reklamowego Meta, aby Meta uczyła się, które reklamy przynoszą realne leady i sprzedaż, oraz optymalizowała pod tym kątem. Wykorzystuje to Twoje własne dane Meta Conversions API.

1. W Menedżerze zdarzeń Meta znajdź identyfikator swojego piksela (zwanego również zbiorem danych) w sekcji Źródła danych i utwórz token dostępu w Ustawieniach, Conversions API, **Wygeneruj token dostępu**.
2. W **Ustawienia → Śledzenie kliknięć reklam**, w sekcji **Wysyłaj wyniki do Meta (opcjonalnie)**, wprowadź **Identyfikator piksela / zbioru danych** oraz **Token dostępu**. Podczas testów możesz dodać **Kod zdarzenia testowego** z karty Zdarzenia testowe w Meta; usuń go, gdy skończysz. Kliknij **Zapisz dane Meta**.
3. Otwórz edytor agenta, przejdź do karty **Tagi** i otwórz tag. W sekcji **Wyślij do Meta** wybierz zdarzenie: **Lead**, **Kontakt**, **Termin**, **Zakup** lub własną nazwę. Opcjonalnie dodaj wartość i walutę.

Od tego momentu, za każdym razem, gdy dany tag zostanie przypisany do kontaktu (przez AI, ręcznie, przez API lub automatyzację), <span data-t="appName">DM Champ</span> wyśle zdarzenie do Meta wraz z zapisanymi danymi kliknięcia kontaktu (`fbc`, `fbp`, adres IP, przeglądarka, strona docelowa) oraz jego zahaszowanym numerem telefonu, adresem e-mail i imieniem, aby Meta mogła powiązać to z reklamą. Kontakt bez dopasowania również wyśle zdarzenie, zawierające tylko zahaszowany telefon, e-mail i imię.

- **Brak podwójnego zliczania:** każde zdarzenie ma stały identyfikator składający się z identyfikatora kontaktu i nazwy tagu. Jeśli Twój CRM wyśle to samo zdarzenie do Meta z tym samym identyfikatorem, Meta zachowa tylko jedno.
- **Okno atrybucji Meta:** Meta przypisuje zdarzenie do reklamy tylko w ramach swojego okna atrybucji, które domyślnie wynosi 7 dni od kliknięcia. Transakcja zamknięta kilka tygodni później nie zostanie zaliczona samodzielnie, dlatego wysyłaj również wcześniejsze zdarzenie, na przykład tag dla zarezerwowanej lub opłaconej konsultacji.

---

## FAQ

**Czy to działa, jeśli moja reklama otwiera WhatsApp bezpośrednio?**
Takie reklamy nie przechodzą przez Twoją stronę internetową, więc skrypt nigdy się nie uruchamia. Meta wysyła szczegóły reklamy wraz z pierwszą wiadomością, zobacz [Atrybucja reklam typu Click-to-WhatsApp](click-to-whatsapp-attribution.md).

**Czy skrypt spowalnia moją stronę lub ustawia pliki cookie?**
Ładuje się w tle (`async`), nie ustawia żadnych plików cookie i nie ładuje niczego innego. Wysyła dane tylko wtedy, gdy odwiedzający kliknie przycisk WhatsApp.

**Czy mogę śledzić Google Ads tak samo jak reklamy Meta?**
Tak. Identyfikatory kliknięć Google (`gclid`, `gbraid`, `wbraid`) oraz wszelkie tagi kampanii są rejestrowane i wyświetlane przy kontakcie. Odsyłanie wyników jest dostępne tylko dla Meta.

**Dlaczego kontakt nie został dopasowany?**
Najczęstsze powody: wiadomość dotarła ponad 15 minut po kliknięciu, numer zapytania został usunięty z wiadomości, numer zapytania jest wyłączony i inny odwiedzający wysłał ten sam tekst lub na stronie nie ma skryptu.

**Moja strona linkuje do dwóch numerów WhatsApp. Czy mogę śledzić tylko jeden?**
Tak. Wpisz ten numer w ustawieniach w polu **Numer WhatsApp**. Pozostaw puste, aby śledzić każdy link WhatsApp.

**Czy mogę później zmienić treść?**
Tak. Zmiany zostaną wprowadzone na Twojej stronie internetowej natychmiast; nie musisz ponownie wklejać skryptu.