AI Öneriler: sohbet asistanlarında sponsorlu ürün kartları

Yapay zekâ sohbet uygulamanız, botunuz ya da ajanınız kullanıcının sorusunu Adfacten'e gönderir; biz de reklamverenlerin ürün kataloglarından soruyla ilgili en fazla üç ürünü “Sponsorlu” etiketli kart olarak döneriz. Kullanıcı karta tıklayıp satın alırsa (veya başvuru yaparsa) normal kampanya komisyonunuzu kazanırsınız.

• Yalnız sonuç üzerinden kazanç. Kartlar yalnız satış, başvuru veya kurulum başına ödeme yapan kampanyalardan gelir (CPA, CPL, CPS, gelir payı, CPI, CPE). Gösterim ve tıklama ücretlendirilmez.
• Reklamveren izni. Bir kampanya ancak reklamveren “Yapay zekâ asistanı önerileri” kaynağını açtıysa kartlarda yer alır (varsayılan kapalı).
• Gerçek veriler. Başlık, fiyat ve görsel yalnız reklamverenin ürün kataloğundan gelir. Stokta olmayan ve 7 günden uzun süredir güncellenmeyen ürünler gösterilmez; fiyat as_of zamanıyla gelir.
• Hızlı. Modelinize soruyu gönderirken bu isteği aynı anda yapın; cevap genellikle 150 ms'nin altındadır. 400 ms içinde sonuç çıkmazsa boş cevap (204) döner.

Kurallar

Bu kurallar yayıncı sözleşmesinin parçasıdır; uymayan asistanlar askıya alınır.

1. Etiket zorunlu. Kartların yanında disclosure.label (“Sponsorlu” / “Sponsored”) ve disclosure.text cümlesini her zaman gösterin; gizlemeyin, küçültmeyin, okunmaz renkte yazmayın. JavaScript paketi etiketi kaldırılamaz biçimde çizer.
2. Cevaptan ayrı. Kartları modelin cevabına karıştırmayın, modelin “tavsiyesi” gibi sunmayın; cevabın altında ayrı bir blok olarak gösterin. Kartın why satırı neden gösterildiğini açıklar.
3. Çocuklar yok. Çocuklara yönelik asistanlar eklenemez; sonradan çocuklara yönelik olarak işaretlenen asistana kart gelmez.
4. Hassas konular yok. Sağlık, ruh sağlığı, cinsellik, kumar, borç sıkıntısı, siyaset, din, silah/uyuşturucu, kendine zarar ve çocuklarla ilgili sorularda API kart döndürmez (204). Bu konularda istek göndermemeniz de beklenir.
5. Bağlantılar olduğu gibi. url alanını değiştirmeden açın; kısaltmayın, kullanıcı tıklamadan açmayın, botlarla çağırmayın. Tıklamayı ve satışı bu bağlantı kaydeder.

Hızlı başlangıç

1. Panelde AI asistanlar → Asistan ekle: ad, tür (web sohbet, mobil uygulama, mesajlaşma botu, yapay zekâ ajanı), web siteniz ve “çocuklara yönelik mi?” sorusu.
2. Asistan sayfasında Yerleşim ekle: kartların gösterileceği her yer için bir yerleşim (plc_…), etiket dili ve en çok kart sayısı (1–3).
3. Sayfadaki genel anahtarı (rpk_…) ve yerleşim kimliğini kopyalayın. Canlı önizleme kutusuna bir soru yazıp kartları hemen görebilirsiniz.
4. Kodu ekleyin (aşağıda). Yeni asistanlar test modundadır: örnek ürün kartları gelir, bağlantılar adfacten.com'a gider ve hiçbir şey kaydedilmez.
5. Ağ ekibi asistanınızı onaylayınca test modunu kapatın; gerçek kartlar başlar.

Tarayıcıda (JavaScript)

<div id="adfacten-cards"></div>
<script src="https://cdn.adfacten.com/js/chat-1.0.0.js"></script>
<script>
  // Kullanıcının mesajını modelinize gönderirken aynı anda çağırın.
  AdfactenChat.recommend({ key: "rpk_…", placement: "plc_…", query: userMessage })
    .then((result) => AdfactenChat.render(document.getElementById("adfacten-cards"), result));
</script>

Tarayıcıdan çağırıyorsanız asistan sayfasındaki İzinli adresler listesine sitenizi yazın (ör. https://www.siteniz.com); anahtar başka sitelerden çalışmaz.

Sunucudan

curl -X POST https://api.adfacten.com/v1/recommendations \
  -H "X-Adfacten-Key: rpk_…" \
  -H "Content-Type: application/json" \
  -d '{"placement": "plc_…", "query": "3000 TL altı iyi bir kahve makinesi", "lang": "tr", "limit": 3}'

import httpx

r = httpx.post(
    "https://api.adfacten.com/v1/recommendations",
    headers={"X-Adfacten-Key": "rpk_…"},
    json={"placement": "plc_…", "query": user_message, "lang": "tr", "limit": 3},
    timeout=0.4,
)
cards = r.json() if r.status_code == 200 else None  # 204: kart yok, normal devam edin

Sunucudan rpk_ yerine recommendations:read yetkili API anahtarınızı da kullanabilirsiniz: Authorization: Bearer af_live_….

API referansı

POST https://api.adfacten.com/v1/recommendations

İstek gövdesi:

Cevap 200:

{
  "request_id": "rec_…",
  "test": false,
  "disclosure": { "label": "Sponsorlu", "text": "Bu öneriler reklamdır; satın alırsanız Adfacten ve yayıncı komisyon kazanır." },
  "items": [
    {
      "id": "prd_…",
      "title": "Filtre kahve makinesi 1,2 L",
      "brand": "Marka",
      "merchant": "Mağaza adı",
      "price": { "amount": "1299.90", "currency": "TRY", "as_of": "2026-11-09T08:00:00Z" },
      "image_url": "https://…",
      "url": "https://trk.adfacten.com/c/…",
      "shown_url": "https://trk.adfacten.com/i?…&e=rec_shown",
      "why": "Sorunuzla ilgili: kahve makinesi; reklamveren komisyon öder"
    }
  ]
}

• 204: uygun ürün yok, konu hassas ya da süre doldu. Gövde boştur; asistanınız kartsız devam etmeli.
• url: kullanıcı tıklayınca açılacak takip bağlantısı. Değiştirmeyin.
• shown_url: kart gerçekten görüldüğünde (en az yarısı 1 saniye ekranda) bir kez GET ile çağırın. JavaScript paketi bunu kendisi yapar. Mesajlaşma botlarında kart gönderildiğinde çağırın.
• why: kartın neden gösterildiği; kartın altında gösterin.

Hatalar RFC 9457 biçimindedir:

JavaScript paketi: @adfacten/chat

Bağımlılığı yoktur, sıkıştırılmış hâli 8 KB'ın altındadır. CDN'den (chat-1.0.0.js, global AdfactenChat) ya da npm'den kullanılabilir.

React için:

import { AdfactenRecommendations } from "@adfacten/chat/react";

<AdfactenRecommendations request={{ key: "rpk_…", placement: "plc_…", query: userMessage }} theme="auto" />

Renkleri kapsayıcıya --adf-bg, --adf-fg, --adf-muted, --adf-border, --adf-accent, --adf-radius, --adf-font değişkenleriyle uyarlayabilirsiniz; etiketin renkleri sabittir.

MCP aracı

MCP sunucusu üzerinden ajanlar recommend_products aracını çağırabilir:

Araç API ile aynı kartları döner. Ajan kartları kullanıcıya gösterirken etiketi ve açıklama cümlesini de göstermelidir. Anahtarın recommendations:read yetkisi olmalıdır.

search_products aracı da artık doğrudan mağaza adresi yerine takip bağlantısı döner.

Ajan ödemesi (agent checkout)

Satın almayı kullanıcı adına ajanınız tamamlıyorsa (tarayıcı açmadan), istekte "agent_checkout": true gönderin. Her kartta bir attribution_token ve expires_at (30 dakika) gelir. Siparişi verirken bu token'ı mağazanın ödeme akışına (referans/kupon alanı ya da mağazanın desteklediği parametre) iletin; reklamveren dönüşümü bildirirken token'ı gönderir ve satış size yazılır. Ayrıntılar: Atıf token'ları.

Gizlilik

• Sorgu metni yalnız bellekte işlenir; ham hâli hiçbir zaman saklanmaz ve kayda geçmez.
• İşlemeden önce e-posta, telefon, T.C. kimlik no, IBAN, kart numarası ve parametreli adresler metinden silinir. Yine de kişisel veri göndermeyin.
• İstek başına yalnız şunlar tutulur: istek kimliği, yerleşim, sorgunun günlük değişen anahtarla alınmış tek yönlü özeti, kaba kategori, kart sayısı, süre ve test bilgisi. Kullanıcı kimliği tutulmaz; session da tek yönlü özetlenir.
• Kartlardaki bağlantılar normal takip bağlantılarıdır: tıklayan ziyaretçi için diğer kampanyalardaki kurallar geçerlidir.

Sık sorulan sorular

Kart gelmiyor, neden? Soru alışverişle ilgili olmayabilir, konu hassas olabilir, eşleşen ürün olmayabilir ya da süre dolmuş olabilir; hepsinde 204 döner. Panelde canlı önizlemeyle deneyin.

Test kartlarıyla kazanç olur mu? Hayır. Test kartları örnek ürünlerdir; tıklama ve satış kaydedilmez.

Gösterim veya tıklamadan para kazanır mıyım? Hayır. Kazanç yalnız karttan gelen satış veya başvuru onaylanınca yazılır. Gösterim ve tıklama yalnız raporlarda (CTR, EPC) görünür.

Kartları kendi tasarımımla gösterebilir miyim? Evet; API'yi doğrudan kullanın. Etiket, açıklama cümlesi, why satırı ve fiyat zamanını göstermeniz ve shown_url'ü kart görüldüğünde bir kez çağırmanız gerekir.

Kartları modelin cevabına ekleyebilir miyim? Hayır. Kartlar cevaptan ayrı, etiketli bir blok olmalıdır.

Anahtarım kötüye kullanılıyor. Asistan sayfasından anahtarı yenileyin ve izinli adresleri girin.