Web sitenizi bağlayın

Kendi web sitenizi ConnectWiz'e bağladığınızda üç şey olmaya başlar:

• ConnectWiz her ziyaretçiyi hangi reklamın, kampanyanın ya da sitenin getirdiğini öğrenir — bağlantının kampanya etiketleri ve ziyaretçi izin verdiyse reklam tıklama kimliği (Google'ın gclid'i, Meta'nın fbclid'i…).
• Sitenizdeki bir WhatsApp bağlantısına dokunuş, sohbete kısa bir ref kodu taşır; böylece konuşma, kişiyi getiren reklama bağlanabilir.
• Sitenizdeki formlar, ziyaretçinin kaynağıyla birlikte ConnectWiz formlarınıza düşer — ConnectWiz'de barındırılan bir formla aynı gönderimler, kişiler, etiketler, bildirimler ve akışlar.

Sitenizde ConnectWiz sohbet aracı zaten çalışıyorsa bunların hepsini onun kodu da yapar — ikinci bir kod, ikinci bir anahtar yok. Sohbet aracı olmayan bir site bunun yerine küçük, ayrı bir betik kullanır. Buradaki hiçbir şey kendi analitiğinizin ya da Google Etiket Yöneticisi'nin yerine geçmez: iki kod da onların yanında çalışır.

Kim kurabilir

Web sitesi bağlantısı tüm planlarda vardır. Kurmak için Entegrasyonları yönet izni (integrations.manage) gerekir. Sonuçların Meta'ya ve Google Ads'e gönderilmesi ve dönüşüm raporu ise Pro ve üstü planlardadır — bkz. Dönüşümleri Meta'ya ve Google Ads'e gönderin.

Web sitesi ekranını açın

Ayarlar → Entegrasyonlar'a gidin ve Web sitesi'ni açın (Reklam altında). İlk seferde siteye bir Site adı verin, Alan adları'nı her satıra bir tane yazın, sitede sohbet aracı çalışıyorsa Sohbet aracı koduyla topla'yı açık bırakın ve Siteyi bağla'ya basın.

• example.com, www.example.com'u da kapsar.
• *.example.com tüm alt alan adlarını kapsar.
• Tarayıcı anahtarı — ve bunun için sohbet aracının anahtarı — yalnız bu alan adlarından çalışır: kodunuzu kopyalayan başka bir alan adındaki sayfa reddedilir.

Birden fazla site bağlayabilirsiniz (Başka bir site ekle); her birinin kendi anahtarları ve ayarları olur. Bağlantı açık bir siteyi silmeden kapatır; Site bağlantısını kaldır siteyi kaldırır — anahtarları hemen çalışmaz olur, gelmiş ziyaretler kalır.

Site betiği ne yapar

Site betiği ne yapar altında:

Anahtar	Anlamı
Reklamdan, kampanya bağlantısından ya da başka bir siteden gelen ziyaretleri kaydet	Bir sayfa görüntülemesi yalnız kampanya işareti (utm etiketleri, reklam tıklama kimliği) taşıyorsa ya da başka bir siteden geldiyse kaydedilir. Kendi sayfalarınızdan ya da adres çubuğuna yazılarak gelen sıradan ziyaretler kaydedilmez.
WhatsApp bağlantılarına ref kodu ekle	Aşağıda WhatsApp ref kodları bölümüne bakın.
Betiğin dolduracağı formlar	Yalnız data-cw-form ile işaretli formlar (varsayılan) ya da Sayfadaki tüm formlar.

Anahtarlar

Bir sitenin iki tür anahtarı vardır. Birbirinin yerine kullanılamazlar. Sohbet aracına bağlı bir site, tarayıcı anahtarının yerine sohbet aracı anahtarını da (sohbet aracı kodunuzda zaten duran anahtar) kabul eder — yalnız sitenin alan adlarından.

Anahtar	Biçimi	Nereye konur	Ne yapabilir
Tarayıcı anahtarı	pk_…	Sayfalarınızın HTML'ine. Bilerek herkese açık.	Yalnız sitenin alan adlarından ziyaret ve WhatsApp tıklaması bildirir. Hiçbir şey okuyamaz, form gönderemez.
Sunucu anahtarı	sk_…	Web sunucunuzun ayarlarına (bir ortam değişkeni), asla bir sayfaya değil.	Form gönderimlerini ConnectWiz'e iletir (kapsam forms:submit). Başka hiçbir şey.

• Yeni tarayıcı anahtarı tarayıcı anahtarını değiştirir. Eskisi hemen çalışmaz olur; sitenizdeki kodu hemen güncelleyin.
• Sunucu anahtarı oluştur anahtara bir ad verir (örneğin Canlı sunucu) ve anahtarı bir kez gösterir: Bu anahtarı şimdi kopyalayın. Bir daha gösterilmez. Kaybederseniz Değiştir'i kullanın — yeni anahtar verilir, eskisi durur.
• İptal et bir sunucu anahtarını kalıcı olarak kapatır. Listede her anahtarın Son kullanım tarihi görünür; sunucunuzun gerçekte hangisini kullandığını buradan görürsünüz.

Kurulum

Sohbet aracı kodunuz bunu zaten yapıyor

Sohbet aracı koduyla topla açıkken Kurulum Kaynak toplama sohbet aracı koduyla birlikte çalışıyor der ve sohbet aracının kendi kodunu gösterir:

<script async
  src="https://api.connectwiz.net/widget/widget.js"
  data-widget-key="…"
></script>

Sohbet aracı sitede zaten kuruluysa eklenecek bir şey yok. Sohbet aracının kodu kaynakları toplar, WhatsApp ref kodlarını ekler ve form alanlarını ayrı betikle tam olarak aynı şekilde, aynı onam kurallarıyla doldurur.

• Hemen başlar; sohbetten önce ve ondan bağımsız: el ile başlatmada (data-manual) Smaibot.init() çağrılmadan önce de, sohbetin kendisi kapalıyken de.
• Site betiği ne yapar altındaki anahtarlar koda dokunmadan uygulanır: sohbet aracı bunları her tarayıcı sekmesinde bir kez ConnectWiz'e sorar.
• Sohbet aracı anahtarı bunun için yalnız sitenin alan adlarından çalışır. Başka bir alan adında sohbet aracı kodu sohbeti yine gösterir ama hiçbir şey toplamaz — bağlantılara ve formlara dokunmaz.
• Bir sayfayı dışarıda tutmak için etikete data-attribution="off" ekleyin (Google Etiket Yöneticisi'nde adrese attribution=off). data-cookie-domain aşağıdaki gibi çalışır.
• Reklamdan gelen bir ziyaretçi sohbet başlattığında sohbet ve ziyaret aynı kişidir: ziyaret, sohbetin oluşturduğu kişiye eklenir ve iniş bir kez sayılır.

Anahtarı açmak bilinçli bir adımdır: sohbet aracı anahtarı sohbetin göründüğü her siteye yapıştırılır; bu yüzden kaynakları yalnız alan adlarını burada yazdığınız yerlerde toplar.

Ayrı betik (sohbet aracı olmayan siteler)

Sohbet aracı çalışmayan bir site için Sohbet aracı koduyla topla'yı kapatın. Kurulum bu durumda tarayıcı anahtarı doldurulmuş ayrı betiği gösterir. Her sayfaya, </head> etiketinden önce yapıştırın:

<script async src="https://api.connectwiz.net/widget/cw-attribution.v1.js" data-key="pk_…"></script>

Buradan değil panelden kopyalayın: paneldeki sürüm anahtarınızı ve seçtiğiniz ayarları taşır. İki kod aynı sayfaya düşerse önce başlayan işi yapar, öteki karışmaz.

Seçenekler

Ayrı betiğin her seçeneği etikette bir data-* özniteliğidir:

Seçenek	Değerler	Varsayılan
data-key	Tarayıcı anahtarınız (pk_…). Zorunlu.	—
data-forms	all sayfadaki tüm formları doldurur	Yalnız data-cw-form taşıyan formlar
data-whatsapp	off WhatsApp bağlantılarına dokunmaz	Açık
data-visits	off ziyaret kaydını durdurur	Açık
data-cookie-domain	.example.com ziyaretçiyi alt alan adlarınız arasında paylaşır	Geçerli alan adı

Anahtarları değiştirdiğinizde panel data-forms, data-whatsapp ve data-visits'i sizin yerinize ekler.

Google Etiket Yöneticisi

Kodu tüm sayfalarda tetiklenen bir Özel HTML etiketi olarak ekleyin. Kapsayıcınız data-* özniteliklerini atıyorsa seçenekleri adrese yazın — betik ikisini de okur:

<script async src="https://api.connectwiz.net/widget/cw-attribution.v1.js?key=pk_…&forms=all"></script>

Formlarınıza ne ekler

Doldurduğu her forma betik iki gizli alan ekler:

• cw_attribution — ziyaretçinin nereden geldiği (JSON);
• cw_event_id — bu gönderim için yeni bir kimlik.

Gönderimde ayrıca dataLayer'a { event: "cw_lead_attribution", cw_event_id } gönderir. Meta pikselinizin Lead olayında olay kimliği olarak aynı değeri kullanın: Meta tarayıcı olayını ve ConnectWiz'in sunucu olayını iki değil bir kez sayar.

Sayfanızın sonradan çizdiği formlar için (açılır pencere, tek sayfalı uygulama) form göründükten sonra window.cwAttribution.fill() çağırın. window.cwAttribution.get() geçerli atıf bloğunu döner.

Onam

Onamı ConnectWiz de tutabilir

ConnectWiz çerez onayı'nı açarsanız aynı kod ziyaretçinin seçimini tutar, etiketlerinize bildirir ve kaydeder — Çerez onayı sayfasına bakın. Orada yapılan seçim aşağıdaki sinyallerden önce gelir. Bir IAB TCF onay aracı (__tcfapi) da okunur — Kendi onay aracınız varsa.

Betik çerez bannerınızı izler. Şu sinyalleri anlar, önce açık olanı:

1. window.cwConsent — betik yüklenmeden önce tanımlayın (window.cwConsent = { ads: true, analytics: true }) ya da ziyaretçi karar verdiğinde bannerınızdan window.cwConsent.update({ ads: true }) çağırın.
2. Google Consent Mode — dataLayer'ınızda zaten bulunan gtag('consent', 'default' | 'update', …) çağrıları. Reklam onamı, ad_storage'ın verilmiş (ve ad_user_data'nın reddedilmemiş) olmasıdır.

Hiç sinyal yoksa onam yok sayılır. Değişen şunlar:

	Pazarlama onamı yokken	Pazarlama onamı varken
Kampanya etiketleri, giriş sayfası, yönlendiren site	Yalnız bu tarayıcı sekmesi için tutulur (oturum belleği)	Birinci taraf _cw_at çerezinde 90 gün tutulur
Reklam tıklama kimlikleri (gclid, gbraid, wbraid, fbclid), Meta'nın _fbp / _fbc'si	Asla okunmaz, tutulmaz, gönderilmez	Ziyaret, WhatsApp tıklaması ve formla gönderilir
Gönderilen sayfa adresi	Tıklama kimliklerinden arındırılır	Olduğu gibi
Ziyarette, WhatsApp tıklamasında ve formun kaynak kaydında ziyaretçinin IP adresi ve tarayıcı bilgisi (user agent)	Saklanmaz (form gönderimi, formunuzdaki onay kutusunun kanıtı olarak kendi kopyasını tutar)	Şifreli saklanır

Ziyaretçi sonradan kabul ederse oturumdaki kopya, adresteki tıklama kimlikleriyle birlikte çereze taşınır. Geri alırsa _cw_at çerezi silinir ve betiğin tuttuğu her kimlik bırakılır. _cw_at bir pazarlama çerezidir: çerez politikanızda böyle listeleyin.

Reklam ölçümü ayrı bir evettir

Kişinin hash'lenmiş telefonunu ve e-postasını reklam ölçümü için Meta ve Google ile paylaşmak kendi açık onamını ister — ad_measurement. Pazarlama çerezlerini kabul etmek bunu içermez; Consent Mode'da da böyle bir sinyal yok. Formunuza isteğe bağlı bir kutu ekleyin (örneğin "Bilgilerimin reklam ölçümü için paylaşılmasına onay veriyorum") ve cevabı iletin:

• tarayıcıda: window.cwConsent.update({ ad_measurement: true }), ya da
• sunucunuzdan, gönderimde: "consent": {"ad_measurement": true}.

Her cevabın neye izin verdiği Dönüşümleri Meta'ya ve Google Ads'e gönderin sayfasında anlatılır. Aydınlatma metniniz bu verinin Meta ve Google ile paylaşılmasını kapsamalıdır.

WhatsApp ref kodları

WhatsApp bağlantılarına ref kodu ekle açıkken sitenizdeki bir wa.me, api.whatsapp.com ya da whatsapp:// bağlantısına dokunuş bir an (bir saniyeden kısa) bekletilir: betik tıklamayı bildirir, kısa bir kod alır ve bağlantıya hazır bir mesaj koyar. WhatsApp örneğin şununla açılır:

Merhaba, bilgi almak istiyorum (ref: K7Q2M)

• Kod, karıştırılması zor harf ve rakamlardan (0/O, 1/I yok) 5 karakterdir, çalışma alanınızda tekildir ve 30 gün geçerlidir.
• ConnectWiz zamanında cevap vermezse ziyaretçi bağlantının ilk haliyle WhatsApp'a geçer. Kaybolan bir atıf, hiçbir şey yapmayan bir düğmeden iyidir.
• Bağlantının zaten kendi metni varsa kod onun sonuna eklenir.
• Ziyaretçi mesajı gönderdiğinde ConnectWiz kodu konuşmanın ilk mesajında bulur, konuşmayı ve kişiyi tıklamaya bağlar ve konuşmada bir Kaynak çipi gösterir — bkz. Lead'i takip edin. Mesaj müşterinin yazdığı gibi saklanır, ama AI asistanı kodu hiç görmez; bu yüzden ne olduğunu sormaz.
• Bir kod bir kez sayılır. Aynı kodla ikinci mesaj, yeniden deneme ya da başka bir konuşma hiçbir şeyi değiştirmez.

Mesajı düzenleyin

WhatsApp bölümünde:

• Mesajların geldiği WhatsApp kanalı ve WhatsApp numarası — sitenizin bağlantılarının hangi numaranızı açtığını not edin. Kod çalışma alanınızda tekil olduğu için bağlı WhatsApp numaralarınızın hepsinde (ve Instagram, Messenger, Telegram ve sohbet penceresinde) tanınır.
• Mesaj (dil) — her dil için bir metin. {ref} ziyaretçinin koduyla değiştirilir; alanda bulunması zorunludur. Metni ziyaretçinin tarayıcı dili seçer; o dil için metin yoksa yazdığınız ilk metin, hiç yoksa ConnectWiz'in kendi cümlesi kullanılır. Önizleme sonucu örnek bir kodla gösterir.

Formlarınızı sunucunuzdan gönderin

Sunucunuz bir form aldığında onu bir sunucu anahtarıyla ConnectWiz'e iletir. ConnectWiz onu ConnectWiz'de doldurulmuş bir form gibi denetler ve aynı adımlardan geçirir — kişi, etiketler, onam, bildirimler, akışlar ve form.submitted webhook'u. Gönderimin kaynağı Web sitesi (sunucu) olarak görünür.

Formu seçin

Gönderimlerin düşeceği form, kod örneklerinin işaret ettiği ConnectWiz formunu seçer. Form yayında olmalıdır; taslak form gönderimleri reddeder. Form kişi oluşturmuyorsa panel uyarır — kişi olmadan reklam platformlarına hiçbir şey gönderilemez.

Hazır lead formunu oluştur tek tıkla bir form kurar: Ad soyad, Telefon, E-posta ve Mesaj; yayında, her gönderimde kişi oluşturan ve bu sitenin formu olarak seçili. Alan anahtarları name, phone, email ve message'dır.

İstek

POST https://api.connectwiz.net/api/intake/forms/{form}/submissions
Authorization: Bearer sk_…
Content-Type: application/json

{form} formun kimliğidir; paneldeki örnekte zaten yazılıdır. Gövde:

Alan	Zorunlu	Nedir
values	Evet	Formun alan anahtarlarıyla cevaplar: {"name": "Ada", "phone": "+905320000000"}.
attribution	Hayır	Formun cw_attribution alanı, geldiği gibi (metin ya da nesne). Formun tamamını values içinde iletirseniz oradan da okunur.
event_id	Hayır	cw_event_id alanı — Meta pikseli tekilleştirme anahtarı.
client_ip	Hayır	Sunucunuzun değil, ziyaretçinin IP adresi.
user_agent	Hayır	Ziyaretçinin tarayıcı User-Agent'ı.
page_url	Hayır	Formun bulunduğu sayfa.
idempotency_key	Hayır	Bu gönderim için kendi kimliğiniz.
consent	Hayır	Ziyaretçi reklam ölçümü kutunuzu işaretlediyse {"ad_measurement": true}. Betiğin zaten kaydettiğinin üstüne eklenir.

Ziyaretçinin gerçek IP'sini ve User-Agent'ını gönderin: Meta lead'i web sitesi olayı sayabilmek için ikisine de ihtiyaç duyar.

Tekrar güvenliği (idempotency). Aynı idempotency_key'i yeniden gönderirseniz — zaman aşımı sonrası yeniden deneme, iki kez çalışan bir kuyruk — ilk gönderim geri döner ("duplicate": true, HTTP 200); ikinci kişi, onam kaydı, dönüşüm ya da webhook oluşmaz.

Örnekler

curl:

curl -X POST 'https://api.connectwiz.net/api/intake/forms/FORM_ID/submissions' \
  -H "Authorization: Bearer $CONNECTWIZ_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "values": {"name": "Ada", "phone": "+905320000000"},
    "attribution": "<formun cw_attribution alanı>",
    "event_id": "<formun cw_event_id alanı>",
    "client_ip": "<ziyaretçinin IP adresi>",
    "user_agent": "<ziyaretçinin User-Agent değeri>",
    "idempotency_key": "<kendi gönderim kimliğiniz>",
    "consent": {"ad_measurement": false}
  }'

PHP:

<?php
$ch = curl_init('https://api.connectwiz.net/api/intake/forms/FORM_ID/submissions');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CONNECTWIZ_SERVER_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'values' => ['name' => $_POST['name'] ?? '', 'phone' => $_POST['phone'] ?? ''],
        'attribution' => $_POST['cw_attribution'] ?? null,
        'event_id' => $_POST['cw_event_id'] ?? null,
        'client_ip' => $_SERVER['REMOTE_ADDR'] ?? null,
        'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? null,
        'page_url' => $_SERVER['HTTP_REFERER'] ?? null,
        'idempotency_key' => $submissionId,
        // Formunuzdaki isteğe bağlı "reklam ölçümü için paylaş" kutusu, varsa.
        'consent' => ['ad_measurement' => !empty($_POST['ad_measurement'])],
    ]),
]);
$response = curl_exec($ch);

Mümkünse bir arka plan işinden gönderin; yavaş bir cevap ziyaretçinizin sayfasını hiç bekletmesin.

Cevaplar

HTTP	Anlamı
201	Alındı. Gövde submission_id, status, contact_id, attribution_touch_id ve duplicate: false taşır.
200	Aynı idempotency_key daha önce gönderilmiş; ilk gönderim duplicate: true ile döner.
401	missing_token ya da unknown_token — anahtar yok, yanlış anahtar ya da sunucu anahtarının yerine tarayıcı anahtarı kullanılmış.
403	revoked_token, missing_scope:forms:submit ya da site_disabled (sitenin bağlantısı kapalı).
404	form_unavailable — form yok ya da yayında değil.
422	Cevaplar formun kendi denetimlerinden geçmedi; errors alanları adlandırır.
429	Bu anahtar için çok fazla istek (dakikada 120). Aynı idempotency_key ile sonra yeniden deneyin.

Şemanın tamamı API referansındadır.

Formlarınızda gizli alanlar

Form oluşturucuda Gizli değer adlı bir alan türü vardır. Ziyaretçi onu hiç görmez.

• ConnectWiz'de barındırılan bir formda değer sayfa adresinden alınır: Okunacağı URL parametresi (boş = alan anahtarı) ya da URL'de yoksa değeri.
• Bağlı bir web sitesinden sunucunuz onu diğer alanlar gibi values içinde gönderir.

Gönderimle birlikte saklamak istediğiniz şeyler için kullanın — bir ürün kodu, sayfanın ait olduğu şube. Ziyaretçinin nereden geldiği için gizli alan gerekmez: o bilgi gönderimle kendiliğinden gelir.

Bir şey geliyor mu?

Bir şey geliyor mu? → Son dokunuşları göster, siteden gelen en son ziyaretleri, form dokunuşlarını ve WhatsApp tıklamalarını listeler: ne zaman, türü, kaynak ve kampanya, hangi tıklama kimliklerinin geldiği (adıyla, değeri asla), ref kodu ve reklam onamı verilip verilmediği.

Denemek için sitenizin bir sayfasını kampanya bağlantısıyla açın (örneğin ?utm_source=test) ya da bir WhatsApp bağlantısına dokunun, sonra Yenile'ye basın. Kampanya etiketi ya da yönlendiren site olmayan sıradan bir ziyaret kaydedilmez — bu bilerek böyledir.

Sonraki adımlar

• Dönüşümleri Meta'ya ve Google Ads'e gönderin
• Google Ads'i bağlayın
• Lead'i takip edin
• Dönüşüm raporu