Attribution Reporting API: entegrasyon kılavuzu

Android'de Özel Korumalı Alan dokümanlarını okurken, çalıştığınız program sürümünü seçmek için Geliştirici Önizlemesi veya Beta düğmesini kullanın (talimatlar farklı olabilir).

Attribution Reporting API, taraflar arası kullanıcı tanımlayıcılarına bağımlı olmadan uygulamalarda ve web'de ilişkilendirme ve dönüşüm ölçümüne yönelik temel kullanım alanlarını destekleyecek şekilde tasarlanmıştır. Günümüzde yaygın olarak kullanılan tasarımlarla karşılaştırıldığında, Attribution Reporting API geliştiricilerinin dikkat etmesi gereken bazı önemli noktalar vardır:

Bu kılavuz, entegrasyon planlamanıza yardımcı olmak amacıyla kapsamlı bir görünüm sağlar. Bu bilgiler, Android Geliştirici Önizlemesi'nde Özel Korumalı Alan'ın şu anki aşamasında henüz uygulanmamış özellikleri içerebilir. Böyle durumlarda zaman çizelgesiyle ilgili yol gösterici bilgiler verilir.

Bu sayfada, tıklamayı veya görüntülemeyi temsil etmek için kaynak, dönüşümü temsil etmek içinse tetikleyici kullanılır.

Aşağıdaki grafikte, ilişkilendirme entegrasyonu için farklı iş akışı seçenekleri gösterilmektedir. Aynı sütunda listelenen bölümler (yeşil daire içinde) paralel olarak işlenebilir. Örneğin, iş ortağı etkileşimi, uygulamadan uygulamaya etkinlik düzeyinde ilişkilendirmeyle aynı anda yapılabilir.

İlişkilendirme entegrasyonu iş akışı şeması

Şekil 1. İlişkilendirme entegrasyonu iş akışı.

Ön koşullar ve kurulum

Attribution Reporting API'yi daha iyi anlamak için bu bölümdeki adımları tamamlayın. Bu adımlar, reklam teknolojisi ekosisteminde API'yi kullanırken anlamlı sonuçlar toplamanızı sağlar.

API'yi tanıyın

  1. Attribution Reporting API ve özellikleri hakkında bilgi edinmek için tasarım teklifini okuyun.
  2. Kullanım alanlarınızda ihtiyaç duyacağınız kodu ve API çağrılarını nasıl ekleyeceğinizi öğrenmek için geliştirici kılavuzunu okuyun.
  3. Özellikle açık sorularla ilgili olarak dokümanlarla ilgili tüm geri bildirimlerinizi gönderin.
  4. Attribution Reporting API ile ilgili güncellemeleri almak için kaydolun. Bu, gelecekteki sürümlerde kullanıma sunulacak yeni özelliklerden haberdar olmanıza yardımcı olur.

Örnek uygulamayı kurma ve test etme

  1. Entegrasyonunuza başlamaya hazır olduğunuzda, Android Studio'daki en son Geliştirici Önizlemesi sürümünü kullanarak gerekli ayarları yapın.
  2. Etkinlik kayıtları ve rapor gönderimleri için sahte sunucu uç noktaları ayarlayın. İnternette erişebileceğiniz araçlarla birlikte kullanabileceğiniz örnekler hazırladık.
  3. Kaynakları ve tetikleyicileri kaydetme hakkında bilgi edinmek için örnek uygulamamızdaki kodu indirip çalıştırın.
    1. Raporların gönderileceği zaman aralığını ayarlayın. API 2 günlük, 7 günlük veya 2 ila 30 günlük özel bir dönemi destekler.
    2. Örnek uygulamayı çalıştırıp kullanarak kaynakları ve tetikleyicileri kaydettikten ve ayarlanan dönemin geçtikten sonra etkinlik düzeyinde rapor ve şifrelenmiş toplanabilir rapor aldığınızı doğrulayın. Raporlarda hata ayıklamanız gerekiyorsa raporlama işlerini zorunlu çalıştırarak raporları daha hızlı oluşturabilirsiniz.
    3. Uygulamadan uygulamaya ilişkilendirme sonuçlarını inceleyin. Bu sonuçlardaki verilerin hem son temas hem de yükleme sonrası destek kayıtları için beklendiği gibi olduğunu onaylayın.

  4. İstemci API'nin ve sunucunun birlikte nasıl çalıştığını öğrendikten sonra, kendi entegrasyonunuzu yönlendirmek için örnek uygulamayı örnek olarak kullanın. Kendi üretim sunucunuzu kurun ve uygulamalarınıza etkinlik kaydı çağrıları ekleyin.

Entegrasyon öncesi

Kuruluşunuzu Android'de Özel Korumalı Alan'a kaydettirin. Bu kayıt, reklam teknolojisi platformlarının gereksiz yere tekrarlanmasını önlemek için tasarlanmıştır. Bu sayede kullanıcının etkinlikleri için gerekenden daha fazla bilgiye erişilebilir.

İş ortağı etkileşimi

Reklam teknolojisi iş ortakları (MMP/SSP/DSP) genellikle entegre ilişkilendirme çözümleri oluşturur. Bu bölümdeki adımlar, reklam teknolojisi iş ortaklarınızla etkileşim kurmada başarılı olmaya hazırlanmanıza yardımcı olur.

  1. Attribution Reporting API'nin test edilmesi ve benimsenmesi hakkında konuşmak için en önemli ölçüm iş ortaklarınızla bir görüşme planlayın. Ölçüm iş ortakları arasında reklam teknolojisi ağları, STP'ler, TTP'ler, reklamverenler veya şu anda birlikte çalıştığınız veya birlikte çalışmak istediğiniz diğer tüm iş ortakları yer alabilir.
  2. Ölçüm iş ortaklarınızla iş birliği yaparak ilk testten benimsemeye kadar entegrasyon için zaman çizelgeleri oluşturun.
  3. Ölçüm iş ortaklarınızla ilişkilendirme tasarımında her birinizin hangi alanları ele alacağını netleştirin.
  4. Zaman çizelgelerini ve uçtan uca testleri senkronize etmek için ölçüm iş ortakları arasında iletişim kanalları oluşturun.
  5. Ölçüm iş ortakları arasında üst düzey veri akışları tasarlayın. Göz önünde bulundurulması gereken önemli noktalar şunlardır:
    • Ölçüm iş ortakları, ilişkilendirme kaynaklarını Attribution Reporting API'ye nasıl kaydeder?
    • Reklam teknolojisi ağları, Attribution Reporting API'yi kullanarak tetikleyicileri nasıl kaydeder?
    • Reklam teknolojileri, API isteklerini nasıl doğrulayacak ve kaynak ve tetikleyici kayıtlarının tamamına nasıl yanıt döndürecek?
    • Attribution Reporting API'nin dışında iş ortakları arasında paylaşılması gereken raporlar var mı?
    • İş ortakları arasında ihtiyaç duyulan başka entegrasyon noktaları veya uyumluluk var mı? Örneğin, sizin ve iş ortaklarınızın dönüşümleri tekilleştirmesi veya toplama anahtarları üzerinde uzlaşmanız gerekiyor mu?
  6. Uygulamadan web'e ilişkilendirme uygunsa Attribution Reporting API'nin tasarımı, testi ve benimsenmesi hakkında konuşmak için web'deki ölçüm iş ortaklarıyla bir görüşme planlayın. Web iş ortaklarıyla görüşmelere başlarken önceki adımdaki sorulara bakın.

Uygulamadan uygulamaya etkinlik düzeyinde ilişkilendirme prototipini oluşturun

Bu bölüm, uygulamanızda veya SDK'nızda etkinlik düzeyindeki raporlarla uygulamalar arası temel bir ilişkilendirme oluşturmanıza yardımcı olur. Toplama sunucusu ilişkilendirmesinin prototipini oluşturmaya başlamadan önce bu bölümün doldurulması gerekir.

  1. Etkinlik kayıtları için bir toplama sunucusu kurun. Bu işlemi sağlanan spesifikasyonu kullanarak sahte sunucu oluşturabilir veya örnek sunucu koduyla kendi sunucunuzu oluşturabilirsiniz.
  2. Reklamlar gösterildiğinde SDK'nıza veya uygulamanıza kaynak etkinlik çağrılarını ekleyin.
    • Dikkat edilmesi gereken kritik noktalar şunlardır:
      • Kaynak etkinlik kimliklerinin kullanılabilir olduğundan ve kaynak kaydı API çağrılarına doğru şekilde iletildiğinden emin olun.
      • Tıklama kaynaklarını kaydetmek için bir "InputEvent" de iletebileceğinizden emin olun.
      • Farklı etkinlik türleri için kaynak önceliğini nasıl yapılandıracağınızı belirleyin. Örneğin, görüntüleme sayısına göre tıklama sayısı gibi yüksek değerli olarak kabul edilen etkinliklere yüksek öncelik atayın.
      • Varsayılan geçerlilik süresi değeri test için uygundur. Alternatif olarak, farklı geçerlilik bitiş aralıkları yapılandırılabilir.
      • Filtreler ve ilişkilendirme aralıkları, test için varsayılan olarak bırakılabilir.
    • İsteğe bağlı olarak göz önünde bulundurulması gereken noktalar şunlardır:
      • Hazırsanız toplama anahtarları tasarlayın.
      • Diğer ölçüm iş ortaklarıyla nasıl çalışmak istediğinizi belirlerken yönlendirme stratejinizi göz önünde bulundurun.
  3. Dönüşüm etkinliklerini kaydetmek için SDK'nıza veya uygulamanıza kayıt tetikleyici etkinlikleri ekleyin.
    • Dikkat edilmesi gereken kritik noktalar şunlardır:
    • İsteğe bağlı olarak göz önünde bulundurulması gereken noktalar şunlardır:
      • Doğruluk testleri yapana kadar tekilleştirme anahtarları oluşturmayı atlayın.
      • Simülasyon testi desteği hazır olana kadar toplama anahtarları ve değerleri oluşturmayı atlayın.
      • Diğer ölçüm iş ortaklarıyla nasıl çalışmak istediğinizi belirleyene kadar yönlendirmeleri atlayın.
      • Test için tetikleyici önceliği gerekli değildir.
      • Filtreler, ilk testte büyük olasılıkla yoksayılabilir.
  4. Reklamlar için kaynak etkinliklerin oluşturulup oluşturulmadığını ve tetikleyicilerin etkinlik raporlarının oluşturulmasına neden olup olmadığını test edin.

Simülasyon testi

Bu bölümde, mevcut dönüşümlerinizi etkinlik raporlarına ve toplanabilir raporlara taşımanın raporlama ve optimizasyon sistemleri üzerindeki olası etkisini test etme konusunda yol gösterici bilgiler verilmektedir. Böylece entegrasyonunuzu tamamlamadan önce etki testine başlayabilirsiniz.

Testler, sahip olduğunuz geçmiş dönüşüm kayıtlarına dayanarak etkinlik ve toplanabilir raporların oluşturulmasını simüle eder ve ardından simüle edilmiş bir toplama sunucusundan toplu sonuçların alınmasını sağlar. Bu sonuçlar, raporlama doğruluğunun nasıl değişeceğini görmek için geçmiş dönüşüm sayılarıyla karşılaştırılabilir.

Tahmini dönüşüm oranı hesaplamaları gibi optimizasyon modelleri, bu modellerin doğruluğunu mevcut veriler temel alınarak oluşturulan modellerle karşılaştırmak için bu raporlar üzerinde eğitilebilir. Bu, farklı toplama anahtar yapıları ve bunların sonuçlar üzerindeki etkisiyle ilgili denemeler yapmak için de bir fırsattır.

  1. Yerel bir makinede Ölçüm Simülasyonu Kitaplığı'nı oluşturun.
  2. Dönüşüm verilerinizin simüle edilen rapor oluşturma aracıyla uyumlu olması için nasıl biçimlendirilmesi gerektiğine ilişkin spec okuyun.
  3. Toplama anahtarlarınızı işletme gereksinimlerine göre tasarlayın.
    • Dikkat edilmesi gereken kritik noktalar şunlardır:
      • Müşterilerinizin veya iş ortaklarınızın bir araya getirmesi gereken kritik boyutları göz önünde bulundurun ve değerlendirmenizi bunlara odaklayın.
      • Gereksinimleriniz için gereken minimum toplu boyut ve kardinalite sayısını belirleyin.
      • Kaynak ve tetikleyici tarafı anahtar parçalarının 128 biti aşmadığından emin olun.
      • Çözümleriniz tetikleyici etkinlik başına birden fazla değere katkıda bulunuyorsa değerleri maksimum katkı bütçesine (L1) göre ölçeklendirdiğinizden emin olun. Bu, gürültünün etkisini en aza indirmeye yardımcı olur.
      • Kampanya düzeyinde toplu dönüşüm sayılarını toplamak için bir anahtar ve coğrafi düzeyde toplu satın alma değerlerini toplamak için bir anahtarın ayarlanmasıyla ilgili bir örneği aşağıda bulabilirsiniz.
  4. Etkinlik raporları ve toplanabilir raporlar oluşturmak için rapor oluşturma aracını çalıştırın.
  5. Özet raporları almak için, birleştirilmiş toplama sunucuları üzerinde birleştirilebilir raporlar çalıştırın.
  6. Yardımcı program denemeleri gerçekleştirme:
    • Dönüşüm raporlama doğruluğunu belirlemek için etkinlik düzeyindeki ve özet raporlardaki dönüşüm toplamlarını geçmiş dönüşüm verileriyle karşılaştırın. En iyi sonuçlar için raporlama testlerini ve karşılaştırmaları reklamveren tabanının geniş ve temsil eden bir kısmı üzerinde çalıştırın.
    • Etkinlik düzeyindeki rapor verilerine ve potansiyel olarak özet rapor verilerine dayanarak modellerinizi yeniden eğitin. Doğruluğu, geçmiş eğitim verilerine dayanan modellerle karşılaştırın.
    • Farklı gruplama stratejilerini deneyin ve bunların sonuçlarınızı nasıl etkilediğini görün.
      • Dikkat edilmesi gereken kritik noktalar şunlardır:
      • Teklifleri ayarlamaya yönelik özet raporların zamanında gelmesi.
      • Cihazdaki ilişkilendirilebilir etkinliklerin ortalama sıklığı. Örneğin, eski satın alma etkinliği verilerine dayanarak geri gelen kullanıcılar.
      • Gürültü düzeyi. Daha fazla grup, daha küçük toplama anlamına gelir ve daha küçük toplama daha fazla gürültü uygulanır.

Prototip toplama sunucusu ilişkilendirmesi: Kurulum

Bu adımlar, kaynağınız ve tetikleyici etkinliklerin toplanabilir raporlarını alabilmenizi sağlar.

  1. Toplama sunucunuzu ayarlayın:
    • AWS hesabınızı ayarlayın.
    • Koordinatörünüzle birlikte toplama hizmetine kaydolun.
    • Sağlanan ikili programları kullanarak AWS'de toplama sunucunuzu oluşturun.
  2. Toplama anahtarlarınızı işletme gereksinimlerine göre tasarlayın. Uygulamadan uygulamaya etkinlik düzeyinde bu görevi daha önce tamamladıysanız bu adımı atlayabilirsiniz.
  3. Birleştirilebilir raporlar için bir koleksiyon sunucusu oluşturun. Daha önce uygulamadan uygulamaya etkinlik düzeyinde bir etkinlik oluşturduysanız bu şablonu yeniden kullanabilirsiniz.

Prototip toplama sunucusu ilişkilendirmesi: Entegrasyon

Bu noktadan sonra ilerlemek için Prototip toplama sunucusu ilişkilendirmesi: Kurulum bölümünü veya Prototipi Uygulamadan Uygulamaya Etkinlik Düzeyinde İlişkilendirme bölümünü tamamlamış olmanız gerekir**.

  1. Kaynağınıza toplama anahtarı verileri ekleyin ve etkinlikleri tetikleyin. Bu, toplama anahtarına dahil etmek üzere SDK'nıza veya uygulamanıza kampanya kimliği gibi reklam etkinliği hakkında daha fazla veri iletmeyi gerektirecektir.
  2. Kaynaktan uygulamadan uygulamaya birleştirilebilir raporlar toplayın ve toplama anahtarı verileriyle kaydettiğiniz etkinlikleri tetikleyin.
  3. Bu toplanabilir raporları toplama sunucusu üzerinden çalıştırırken farklı toplu işleme stratejilerini test edin ve bunların sonuçlarınızı nasıl etkilediğini görün.

İsteğe bağlı özelliklerle tasarımı tekrarlayın

Ölçüm çözümüne ekleyebileceğiniz ek özellikler aşağıda verilmiştir.

  1. Hata ayıklama anahtarı ayarlamak, Attribution Reporting API tarafından oluşturulan raporlarla birlikte kaynak veya tetikleyici etkinliğin değiştirilmemiş bir raporunu almanıza olanak tanır. Entegrasyon sırasında raporları karşılaştırmak ve hataları bulmak için hata ayıklama anahtarlarını kullanabilirsiniz.

İlişkilendirme davranışlarını özelleştirin

  1. Yükleme sonrası tetikleyicileri için ilişkilendirme
    • Bu özellik, yükleme sonrası tetikleyicilerinin, yüklemeyi sağlayan aynı ilişkilendirme kaynağıyla ilişkilendirilmesi gerektiğinde (daha yakın zamanda gerçekleşmiş başka uygun ilişkilendirme kaynakları olsa bile) kullanılabilir.
    • Örneğin, bir kullanıcının yükleme sağlayan bir reklamı tıkladığı bir durum olabilir. Kullanıcı, reklam yüklendikten sonra başka bir reklamı tıklayıp satın alma işlemi gerçekleştirir. Bu durumda reklam teknolojisi şirketi, satın alma işleminin yeniden etkileşim tıklaması yerine ilk tıklamayla ilişkilendirilmesini isteyebilir.
  2. Etkinlik düzeyindeki raporlarınızdaki verilerde hassas ayarlar yapmak için filtreleri kullanın
    • Dönüşüm filtreleri, seçili tetikleyicileri yoksayıp etkinlik raporlarından hariç tutacak şekilde ayarlanabilir. İlişkilendirme kaynağı başına tetikleyici sayısıyla ilgili sınırlar olduğundan filtreler, etkinlik raporlarınıza yalnızca en yararlı bilgileri sağlayan tetikleyicileri eklemenize olanak tanır.
    • Filtreler, bazı tetikleyicileri seçerek filtreleyerek de yoksaymak için de kullanılabilir. Örneğin, uygulama yüklemelerini hedefleyen bir kampanyanız varsa yükleme sonrası tetikleyicileri filtreleyerek söz konusu kampanyadaki kaynaklarla ilişkilendirilmesini engelleyebilirsiniz.
    • Filtreler, kaynak verilere göre tetikleyici verilerini özelleştirmek için de kullanılabilir. Örneğin, bir kaynak "product" : ["1234"] öğesini belirtebilir. Burada ürün filtre anahtarı, 1234 ise değerdir. Filtre anahtarı "product" (ürün) olan ve "1234" dışında bir değere sahip olan tüm tetikleyiciler yoksayılır.
  3. Özelleştirilmiş kaynak ve tetikleyici önceliği
    • Bir tetikleyici ile birden fazla ilişkilendirme kaynağının ilişkilendirilebilmesi veya bir kaynakla birden fazla tetikleyici ilişkilendirilebilmesi durumunda, belirli kaynak/tetikleyici ilişkilendirmelerini diğerlerine göre önceliklendirmek için imzalı 64 bitlik bir tam sayı kullanabilirsiniz.

MMP'lerle ve diğerleriyle çalışma

  1. Kaynak ve tetikleyici etkinlikler için diğer üçüncü taraflara yönlendirmeler
    • Yönlendirme URL'lerini, birden fazla reklam teknolojisi platformunun bir isteği kaydetmesine izin verecek şekilde ayarlayabilirsiniz. Bu, ilişkilendirmede ağlar arası tekilleştirmeyi etkinleştirmek için kullanılabilir.
  2. Tekilleştirme anahtarları
    • Bir reklamveren aynı tetikleyici etkinliği kaydetmek için birden fazla reklam teknolojisi platformu kullandığında, bu yinelenen raporları netleştirmek için tekilleştirme anahtarı kullanılabilir. Tekilleştirme anahtarı sağlanmazsa yinelenen tetikleyiciler her reklam teknolojisi platformuna benzersiz olarak bildirilebilir.

Platformlar arası ölçümle çalışma

  1. Uygulamalar arası ve web ilişkilendirme (4. çeyreğin sonlarında kullanıma sunulacaktır)
    • Kullanıcının uygulamada reklamı görüp mobil veya uygulama tarayıcısında dönüşüm gerçekleştirdiği veya tam tersinin gerçekleştiği kullanım durumlarını destekler.