Google Ads API Dış Promosyon Kodu Takibi Nasıl Kurulur?

Kısa yanıt: yeni alan ne işe yarar?

Google Ads API v26.1, dış sistemde kullanılan promosyonlar için PromotionAsset.external_redeem_info alanını ekledi. Alan, promosyon kodunun türünü, kaynağını ve gerektiğinde iş ortağı sistemindeki promosyon kimliğini belirtmeye yarar. Reklam ile dış kullanım kaydı arasında izlenebilir bir eşleme kurmak isteyen ekip, önce hesabın bu özelliğe uygunluğunu ve kullandığı API istemcisinin v26.1 alanlarını desteklediğini doğrulamalıdır. Google Ads API sürüm notu değişikliği 28 Ekim 2026 altında duyurur.

Bu konu, bütçenin ağ kanallarına nasıl paylaştırıldığını anlatan Google Ads kanal önceliği rehberinden ayrıdır. Buradaki amaç reklam varlığındaki promosyon tanımıyla harici kod kullanımı arasında güvenilir kayıt bağı kurmaktır. Alanın eklenmesi tek başına dönüşüm, satış veya harcama performansı sonucu üretmez.

Önce iş akışını tanımlayın

Bir promosyon kodunun reklamda görünmesi ile müşterinin kodu gerçekten kullanması farklı olaylardır. İşletme, kodları kendi sisteminde mi oluşturuyor, yoksa desteklenen entegrasyonda Google tarafından oluşturulan kodları mı kullanıyor? Kod bir kez mi geçerli, tekrar kullanılabilir mi? Kullanım kasada, web ödemesinde veya başka bir iş ortağı sisteminde mi kayda geçiyor? Bu soruların cevabı, API alanına hangi değerin yazılacağını belirler.

Önce bir veri sözlüğü hazırlayın. Reklam varlığı kimliği, iç promosyon kimliği, kod kaynağı, kod türü, geçerlilik tarihleri, kullanım durumu ve iptal durumu ayrı alanlar olsun. Kodun kendisini herkesin görebildiği genel rapora dökmeyin. Rapor için çoğu durumda promosyon kimliği ve toplulaştırılmış durum yeterlidir. Müşteri kişisel verisi tutulacaksa kendi erişim ve saklama kurallarınıza göre ayrıca değerlendirin.

Bu akışın sınırını da belirleyin: Harici kullanım verisini hangi sistemin ürettiği, hata halinde hangi ekibin düzelttiği ve reklam platformuna hangi verinin aktarılacağı yazılı olmalı. Ölçüm planı olmadan yalnızca API alanını doldurmak, kampanya sonucunu açıklamaz.

Alanlar nasıl eşlenir?

Resmî ExternalRedeemInfo tanımı, code_source ve code_type alanlarını zorunlu ve değiştirilemez olarak gösterir. Kod kaynağı müşteri tarafından yüklenen veya Google tarafından oluşturulan kod olabilir; kod türü tek kullanım ya da çoklu kullanım biçimindedir. partner_promotion_id de değiştirilemez; kaynak GOOGLE_GENERATED ise zorunludur. Kimlik sayı veya metin olabilir, fakat kabul edilen biçim hesabın promosyon entegrasyonuna bağlıdır. Alan referansı bu koşulları ayrı ayrı belirtir.

Uygulama ekibi eşlemeyi önce örnek kayıtlarla doğrulamalıdır. Tek kullanımlık kodu çok kullanımlı olarak etiketlemek, daha sonra kullanım verisini yorumlamayı zorlaştırır. İç sistemdeki promosyon kimliği değişebiliyorsa bunu doğrudan kalıcı dış kimlik gibi kullanmak da iyi bir varsayım değildir. Değiştirilemez alanlar için güncelleme gereksinimi doğduğunda varlık yaşam döngüsü planı gerekir; mevcut kaydı sessizce farklı anlamla kullanmayın.

PromotionAsset referansı, external_redeem_info alanının yalnızca dış kullanım izleme yeteneğine sahip promosyonlar için ayarlandığını söyler. Dolayısıyla her reklam hesabı ve her promosyon türü için otomatik geçerli kabul etmeyin. Hesap, entegrasyon ve seçilen promosyon varlığı üzerinde uygunluğu ayrı test edin. Resmî PromotionAsset belgesi kapsamı bu şekilde sınırlar.

Uygulama adımları

İlk olarak mevcut promosyon kayıtlarını çıkarın ve her birinin sahibini belirleyin. İkinci olarak kaynak ile türü iç sistemde kesin tanımlayın; boş veya çelişkili kayıtları API'ye taşımayın. Üçüncü olarak test hesabında alanın kullanılabilirliğini ve istemci kütüphanesi sürümünü doğrulayın. Dördüncü olarak örnek varlık oluşturma veya güncelleme akışını, gerçek bir satışa bağlı olmayan test verisiyle çalıştırın. Beşinci olarak dönen varlık bilgisini ve dış sistemdeki kimliği karşılaştırın.

Bir promosyonun uygulama koşulları, başlangıç ve bitiş tarihi ile kullanıldığı kanal da iş akışında açık olmalı. Kullanıcı reklamdan farklı bir koşul görüyorsa sorun API alanından önce mesaj ve hedef sayfa tutarlılığındadır. Kullanım kaydı geldiğinde yalnızca “kod kullanıldı” bilgisini değil, hangi promosyon sürümüne ait olduğunu da ayırt edin. İptal veya iade gibi sonradan değişen işlemleri ayrı durum olarak tutun.

Operasyon ekibinin okuyabileceği kısa bir kontrol panosu yararlıdır: reklam varlığına bağlı promosyon, dış sistem kaydı var mı, kullanım durumu gecikti mi, biçim hatası alındı mı? Bu gösterge seti bir öneridir; Google'ın otomatik sunduğu hazır rapor olduğu iddiası değildir. Panoyu kurarken erişim haklarını ve kodların gizliliğini koruyun.

Hata ve belirsizlik nasıl yönetilir?

Google Ads API sürüm notu, iş ortağı kimliği biçimi hesap entegrasyonunun kabul ettiği türle uyuşmazsa PARTNER_PROMOTION_ID_TYPE_INCOMPATIBLE hatasının dönebileceğini belirtir. Bu hata geldiğinde kimliği rastgele metne çevirmek yerine hesabın beklediği biçimi ve iç sistemdeki asıl kimliği karşılaştırın. Aynı promosyonu tekrar tekrar oluşturmak mükerrer kayıt oluşturabilir; önce önceki denemenin sonucu okunmalıdır.

Bir kullanım dış sistemde görünüp reklam raporunda görünmüyorsa gecikme, entegrasyon kapsamı, kimlik eşlemesi ve rapor tanımı ayrı kontrol edilir. Kaydı doğrudan kampanyanın dönüşümüne eşitlemeyin. Reklam tıklaması, promosyon gösterimi, kod üretimi ve gerçek kullanım farklı olaylardır. Aralarındaki ilişki ancak ölçüm tasarımı ve doğrulanmış veriyle kurulabilir.

Hesapta özellik görünmüyorsa bunun nedenini resmî erişim veya entegrasyon koşuluyla doğrulayın. Sürüm notunda alanın varlığı, bütün müşterilerin aynı gün kullanabileceği anlamına gelmez. Teknik erişim ve iş ihtiyacını ayrı karar olarak ele alın.

Hangi durumda bu entegrasyon anlamlı?

Teklif yalnızca reklam metninde duyuruluyor ve harici kod kullanımı hiç izlenmiyorsa kapsamlı bir eşleme projesi gerekmeyebilir. Birden fazla kanal, kasa ya da iş ortağı aynı promosyonu kullanıyor ve ekip gerçek kullanım ile reklam tanımını bağlamak istiyorsa veri sözlüğü ve entegrasyon daha değerli hale gelir. Karar, kodların nasıl üretildiği ve kullanım kaydının ne kadar güvenilir olduğuyla verilmelidir.

Başlangıç için mevcut promosyon akışınızı, kullanılan Google Ads API sürümünü ve dış sistemdeki kod alanlarını listeleyin. Webinle'nin Google ve Meta reklam optimizasyonu hizmeti üzerinden bu akışı paylaşarak mesaj, ölçüm ve teknik entegrasyon kapsamını birlikte değerlendirebilirsiniz. Hedef, doğrulanabilir bir kullanım kaydı oluşturmaktır; belirli bir reklam sonucu vaat etmek değildir.