Attribution Reporting API: entegrasyon kılavuzu

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

Attribution Reporting API, taraflar arası kullanıcı tanımlayıcılarına bağımlı olmadan uygulamalar ve web'de ilişkilendirme ve dönüşüm ölçümü için temel kullanım alanlarını destekleyecek şekilde tasarlanmıştır. Attribution Reporting API'yi uygulayanlar, günümüzdeki yaygın tasarımlara kıyasla bazı önemli üst düzey noktaları göz önünde bulundurmalıdır:

  • Etkinlik düzeyindeki raporlar, düşük doğruluklu dönüşüm verilerini içerir. Az sayıda dönüşüm değeri iyi sonuç verir.
  • Toplanabilir raporlar, daha yüksek doğrulukta dönüşüm verileri içerir. Çözümleriniz, işletme gereksinimlerinize ve 128 bit sınırına göre toplama anahtarları tasarlamalıdır.
  • Çözümünüzün veri modelleri ve işleme sürecinde kullanılabilir tetikleyiciler için sıklık sınırları, tetikleyici etkinlikleri göndermeyle ilgili zaman gecikmeleri ve API tarafından uygulanan gürültü dikkate alınmalıdır.

Bu kılavuz, entegrasyon planlamanıza yardımcı olmak için kapsamlı bir görünüm sunar. Bu görünüm, Android'deki Özel Korumalı Alan geliştirici önizlemesinin mevcut aşamasında henüz uygulanmamış özellikleri içerebilir. Bu durumlarda zaman çizelgesi rehberliği sağlanır.

Bu sayfada, tıklamayı veya görüntülemeyi göstermek için kaynak, dönüşümü göstermek için ise 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şille daire içine alınmış) paralel olarak çalışılabilir. Örneğin, iş ortağı etkileşimi, uygulama içi etkinlik düzeyinde ilişkilendirme ile aynı anda yapılabilir.

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

Ön koşullar ve kurulum

İlişkilendirme Raporlama API'si hakkındaki bilginizi artırmak 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ğlayacak şekilde ayarlanmıştır.

API hakkında bilgi edinme

  1. Attribution Reporting API ve özellikleri hakkında bilgi edinmek için tasarım önerisini okuyun.
  2. Kullanım alanlarınız için ihtiyacınız olacak kodu ve API çağrılarını nasıl dahil edeceğinizi öğrenmek için geliştirici kılavuzunu okuyun.
  3. İlişkilendirme Raporlama API'si ile ilgili güncellemeleri almak için kaydolun. Bu sayede, gelecekteki sürümlerde kullanıma sunulacak yeni özelliklerden haberdar olabilirsiniz.

Örnek uygulamayı ayarlama ve test etme

  1. Entegrasyonunuza başlamaya hazır olduğunuzda Android Studio'daki en yeni geliştirici önizlemesini yükleyin.
  2. Etkinlik kayıtları ve rapor teslimatları için sahte sunucu uç noktaları oluşturun. İnternetteki araçlarla birlikte kullanabileceğiniz örnekler sağladık.
  3. Kaynakları ve tetikleyicileri kaydetme konusunda bilgi edinmek için örnek uygulamamızdaki kodu indirip çalıştırın.
    1. Rapor gönderme zaman aralığını ayarlayın. API; 2 gün, 7 gün veya 2 ila 30 gün arasında özel bir dönemi destekler.
    2. Kaynakları ve tetikleyicileri örnek uygulamayı çalıştırıp kullanarak kaydettikten ve belirlenen süre geçtikten sonra, etkinlik düzeyinde bir rapor ve şifrelenmiş bir toplu hale getirilebilir rapor aldığınızı doğrulayın. Raporlarda hata ayıklamanız gerekiyorsa raporlama işlerini zorunlu olarak çalıştırarakraporları daha hızlı oluşturabilirsiniz.
    3. Uygulamadan uygulamaya ilişkilendirme sonuçlarını inceleyin. Bu sonuçlardaki verilerin hem son dokunuş hem de yükleme sonrası durumlar için beklendiği gibi olduğunu onaylayın.

  4. İstemci API'si ile sunucunun birlikte nasıl çalıştığını anladıktan sonra kendi entegrasyonunuza rehberlik etmesi için örnek uygulamayı kullanın. Kendi üretim sunucunuzu oluşturun ve uygulamalarınıza etkinlik kaydı çağrıları ekleyin.

Entegrasyon öncesi

Kuruluşunuzu Android'de Özel Korumalı Alan'a kaydedin. Bu kayıt, reklam teknolojisi platformlarının gereksiz yere çoğalmasını önlemek için tasarlanmıştır. Bu sayede, kullanıcının etkinlikleriyle ilgili gerekenden daha fazla bilgiye erişim sağlanır.

İş 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şimde başarılı olmanıza yardımcı olur.

  1. Attribution Reporting API'nin test edilmesi ve kullanıma sunulması hakkında görüşmek için en iyi ölçüm iş ortaklarınızla bir görüşme planlayın. Ölçüm iş ortakları arasında reklam teknolojisi ağları, SSP'ler, DSP'ler, reklamverenler veya birlikte çalıştığınız ya da çalışmak istediğiniz diğer iş ortakları yer alabilir.
  2. İlk testten kullanıma kadar entegrasyon zaman çizelgelerini tanımlamak için ölçüm iş ortaklarınızla birlikte çalışın.
  3. Ölçüm iş ortaklarınızla birlikte, her birinizin ilişkilendirme tasarımında hangi alanları kapsayacağını netleştirin.
  4. Zaman çizelgeleri ve uçtan uca testler konusunda senkronize olmak 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 kaydedecek?
    • Reklam teknolojisi ağları, Attribution Reporting API ile tetikleyicileri nasıl kaydedecek?
    • Her reklam teknolojisi, API isteklerini nasıl doğrulayacak ve kaynak ile tetikleyici kayıtlarını tamamlamak için yanıtları nasıl döndürecek?
    • Attribution Reporting API dışında iş ortaklarıyla paylaşılması gereken raporlar var mı?
    • İş ortakları arasında başka entegrasyon noktaları veya uyum sağlanması gereken alanlar var mı? Örneğin, sizin ve iş ortaklarınızın dönüşümleri tekilleştirmek veya toplama anahtarlarını eşleştirmek için çalışması gerekiyor mu?
  6. Uygulamadan web'e ilişkilendirme geçerliyse web'deki ölçüm iş ortaklarıyla Attribution Reporting API'nin tasarımı, testi ve benimsenmesi hakkında görüşmek için bir toplantı planlayın. Web iş ortaklarıyla görüşmelere başlarken önceki adımdaki soruları referans alın.

Uygulamadan uygulamaya etkinlik düzeyinde ilişkilendirme prototipi

Bu bölüm, uygulamanızda veya SDK'nızda etkinlik düzeyinde raporlarla temel bir uygulama-uygulama ilişkilendirmesi ayarlamanıza yardımcı olur. Prototip oluşturma toplama sunucusu ilişkilendirmesine başlamadan önce bu bölümün tamamlanması gerekir.

  1. Etkinlik kayıtları için bir toplama sunucusu ayarlayın. Bunu, sağlanan spesifikasyonu kullanarak sahte bir sunucu oluşturarak veya örnek sunucu kodu ile kendi sunucunuzu ayarlayarak yapabilirsiniz.
  2. Reklamlar gösterildiğinde SDK'nıza veya uygulamanıza kaynak etkinliği çağrılarını kaydet ekleyin.
    • Önemli hususlar şunlardır:
      • Kaynak etkinlik kimliklerinin kullanılabilir olduğunu ve kaynak kayıt API çağrılarına doğru şekilde iletildiğini doğrulayın.
      • Tıklama kaynaklarını kaydetmek için bir "InputEvent" de iletebildiğinizi doğrulayın.
      • Farklı etkinlik türleri için kaynak önceliğini nasıl yapılandıracağınızı belirleyin. Örneğin, görüntülemelerden daha değerli olduğu düşünülen tıklamalar gibi etkinliklere yüksek öncelik atayın.
      • Son kullanma tarihi için varsayılan değer, test için uygundur. Alternatif olarak, farklı geçerlilik süreleri yapılandırılabilir.
      • Test için filtreler ve ilişkilendirme aralıkları varsayılan olarak bırakılabilir.
    • İsteğe bağlı olarak dikkate alınabilecekler ş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 tetikleyici etkinlikleri kaydetme işlevini ekleyin.
    • Önemli hususlar şunlardır:
    • İsteğe bağlı olarak dikkate alınabilecekler ş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ğinize karar verene kadar yönlendirmeleri atlayın.
      • Tetikleme önceliği, test için gerekli değildir.
      • İlk testlerde filtreler yoksayılabilir.
  4. Reklamlar için kaynak etkinliklerinin oluşturulduğunu ve tetikleyicilerin etkinlik raporlarının oluşturulmasına yol açtığını test edin.

Simülasyon testi

Bu bölümde, mevcut dönüşümlerinizi etkinlik ve toplanabilir raporlara taşımanın raporlama ve optimizasyon sistemleri üzerindeki olası etkisini test etme konusunda size yol gösterilecektir. Bu sayede, entegrasyonunuzu tamamlamadan önce etki testine başlayabilirsiniz.

Test, geçmiş dönüşüm kayıtlarınıza göre etkinlik ve toplanabilir raporların oluşturulması simüle edilerek ve ardından toplu sonuçlar simüle edilmiş bir toplama sunucusundan alınarak yapılır. 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 verilere dayalı modellerle karşılaştırmak için bu raporlar üzerinde eğitilebilir. Bu, farklı toplama anahtarı yapılarını ve bunların sonuçlar üzerindeki etkisini denemek için de bir fırsattır.

  1. Yerel bir makinede Ölçüm Simülasyon Kitaplığı'nı ayarlayın.
  2. Dönüşüm verilerinizin, simüle edilmiş rapor oluşturucuyla uyumlu olması için nasıl biçimlendirilmesi gerektiğiyle ilgili şartnameyi okuyun.
  3. Toplama anahtarlarınızı işletme şartlarına göre tasarlayın.
    • Önemli hususlar şunlardır:
      • Müşterilerinizin veya iş ortaklarınızın toplaması gereken önemli boyutları göz önünde bulundurun ve değerlendirmenizi bu boyutlara 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ığını doğrulayın.
      • Çözümleriniz tetikleme etkinliği başına birden fazla değere katkıda bulunmayı içeriyorsa değerleri maksimum katkı bütçesi olan L1'e göre ölçeklendirdiğinizden emin olun. Bu, gürültünün etkisini en aza indirmenize yardımcı olur.
      • Burada, 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 ayarlamayı ayrıntılı olarak açıklayan bir örnek verilmiştir.
  4. Etkinlik ve toplanabilir raporlar oluşturmak için rapor oluşturucuyu çalıştırın.
  5. Özet raporlar almak için toplanabilir raporları simüle edilmiş toplama sunucularında çalıştırın.
  6. Yardımcı program denemeleri yapın:
    • Dönüşüm raporlama doğruluğunu belirlemek için etkinlik düzeyindeki ve özet raporlardaki toplam dönüşümleri geçmiş dönüşüm verileriyle karşılaştırın. En iyi sonuçları elde etmek için raporlama testlerini ve karşılaştırmalarını reklamveren tabanının geniş ve temsili bir bölümünde çalıştırın.
    • Modellerinizi etkinlik düzeyindeki rapor verilerine ve muhtemelen özet rapor verilerine göre yeniden eğitin. Doğruluğu, geçmiş eğitim verileri üzerinde oluşturulan modellerle karşılaştırın.
    • Farklı gruplandırma stratejilerini deneyerek sonuçlarınızı nasıl etkilediklerini görün.
      • Önemli hususlar arasında şunlar yer alır:
      • Teklifleri ayarlamaya yönelik özet raporların zamanında oluşturulması.
      • Cihazdaki ilişkilendirilebilir etkinliklerin ortalama sıklığı. Örneğin, geçmiş satın alma etkinlikleri verilerine göre geri dönen etkin olmayan kullanıcılar.
      • Gürültü seviyesi. Daha fazla toplu iş, daha küçük toplama anlamına gelir. Daha küçük toplama ise daha fazla gürültü uygulanması anlamına gelir.

Prototip toplama sunucusu ilişkilendirmesi: Kurulum

Bu adımlar, kaynak ve tetikleyici etkinliklerinizin toplanabilir raporlarını alabilmenizi sağlar.

  1. Toplama sunucunuzu ayarlayın:
    • AWS hesabınızı oluşturun.
    • Koordinatörünüzle birlikte Aggregation Service'e kaydolun.
    • Sağlanan ikili dosyalardan AWS'de toplama sunucunuzu ayarlayın.
  2. Toplama anahtarlarınızı işletme şartlarına göre tasarlayın. Bu görevi uygulamadan uygulamaya etkinlik düzeyi bölümünde daha önce tamamladıysanız bu adımı atlayabilirsiniz.
  3. Toplanabilir raporlar için bir toplama sunucusu ayarlayın. Uygulamadan uygulamaya etkinlik düzeyi bölümünde daha önce oluşturduğunuz bir dönüşüm izleme etiketini yeniden kullanabilirsiniz.

Prototip toplama sunucusu ilişkilendirmesi: Entegrasyon

Bu noktadan sonra devam etmek için Prototip toplama sunucusu ilişkilendirmesi: Kurulum bölümünü veya Prototip uygulama-uygulama etkinlik düzeyinde ilişkilendirme bölümünü tamamlamış olmanız gerekir.

  1. Kaynak ve tetikleme etkinliklerinize toplama anahtarı verileri ekleyin. Bu işlem, büyük olasılıkla toplama anahtarına dahil etmek için kampanya kimliği gibi reklam etkinliği hakkında daha fazla verinin SDK'nıza veya uygulamanıza iletilmesini gerektirir.
  2. Kaynaklardan uygulamadan uygulamaya toplanabilir raporlar toplayın ve toplama anahtarı verileriyle kaydettiğiniz etkinlikleri tetikleyin.
  3. Bu toplanabilir raporları toplama sunucusunda çalıştırırken farklı gruplandırma stratejilerini test edin ve sonuçlarınızı nasıl etkilediklerini görün.

İsteğe bağlı özelliklerle tasarımı yineleme

Aşağıda, ölçüm çözümünüze ekleyebileceğiniz ek özellikler verilmiştir.

  1. Bir hata ayıklama anahtarı ayarladığınızda, Attribution Reporting API tarafından oluşturulan raporların yanı sıra bir kaynak veya tetikleyici etkinliğin değiştirilmemiş bir raporunu alabilirsiniz. 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ştirme

  1. Yükleme sonrası tetikleyiciler için ilişkilendirme
    • Bu özellik, yükleme sonrası tetikleyicilerin daha yakın zamanda gerçekleşen başka uygun ilişkilendirme kaynakları olsa bile yüklemeyi sağlayan ilişkilendirme kaynağıyla ilişkilendirilmesi gerektiği durumlarda kullanılabilir.
    • Örneğin, kullanıcının yüklemeye yol açan bir reklamı tıkladığı bir durum olabilir. Yükleme tamamlandıktan sonra kullanıcı 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 verileri hassas bir şekilde ayarlamak için filtreleri kullanma
    • Dönüşüm filtreleri, seçilen tetikleyicileri yoksayacak ve bunları etkinlik raporlarından hariç tutacak şekilde ayarlanabilir. Her ilişkilendirme kaynağı için tetikleyici sayısı sınırlı olduğundan filtreler, etkinlik raporlarınızda yalnızca en yararlı bilgileri sağlayan tetikleyicileri dahil etmenize olanak tanır.
    • Filtreler, bazı tetikleyicileri seçerek filtrelemek ve etkili bir şekilde yok saymak için de kullanılabilir. Örneğin, uygulama yüklemelerini hedefleyen bir kampanyanız varsa yükleme sonrası tetikleyicilerin bu kampanyadaki kaynaklarla ilişkilendirilmesini filtreleyebilirsiniz.
    • Filtreler, tetikleyici verilerini kaynak verilere göre özelleştirmek için de kullanılabilir. Örneğin, bir kaynak "product" : ["1234"] değerini belirtebilir. Burada product filtre anahtarı, 1234 ise değerdir. Filtre anahtarı "product" olan ve değeri "1234" dışında olan tüm tetikleyiciler yoksayılır.
  3. Özelleştirilmiş kaynak ve tetikleyici önceliği
    • Bir tetikleyiciyle birden fazla ilişkilendirme kaynağı ilişkilendirilebiliyorsa veya bir kaynağa birden fazla tetikleyici ilişkilendirilebiliyorsa belirli kaynak ya da tetikleyici ilişkilendirmelerine diğerlerine göre öncelik vermek için imzalı 64 bitlik bir tam sayı kullanabilirsiniz.

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

  1. Kaynak ve tetikleyici etkinlikler için diğer üçüncü taraflara yönlendirmeler
    • Birden fazla reklam teknolojisi platformunun istek kaydetmesine izin vermek için yönlendirme URL'leri ayarlayabilirsiniz. Bu, ilişkilendirmede ağlar arası yinelenenleri kaldırma özelliğini 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. Uygulama ve web siteleri arası ilişkilendirme (4. çeyreğin sonlarında kullanıma sunulacaktır)
    • Kullanıcının uygulamada reklam gördükten sonra mobil veya uygulama tarayıcısında dönüşüm gerçekleştirdiği ya da bunun tam tersi durumları destekler.