Attribution Reporting API: entegrasyon kılavuzu

Android'de Özel Korumalı Alan dokümanlarını okurken, talimatlar değişiklik gösterebileceğinden, üzerinde ç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ı kalmadan uygulamalarda 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 uygulayıcıları, günümüzde yaygın olan tasarımlara kıyasla bazı önemli üst düzey hususları dikkate almalıdır:

  • Etkinlik düzeyindeki raporlar düşük kaliteli dönüşüm verileri içerir. Az sayıda dönüşüm değeri kullanmak iyi sonuçlar verir.
  • Birleştirilebilir raporlar daha yüksek doğruluktaki dönüşüm verilerini içerir. Çözümleriniz, toplama anahtarlarını işletme gereksinimlerinize ve 128 bit sınırına göre tasarlamalıdır.
  • Çözümünüzün veri modelleri ve işleme işlemleri, kullanılabilir tetikleyiciler için hız sınırlarını, tetikleyici etkinliklerini göndermedeki zaman gecikmeleri ve API tarafından uygulanan gürültüyü dikkate almalıdır.

Entegrasyon planlamanıza yardımcı olmak için bu kılavuzda, Android Developer Preview'daki Özel Korumalı Alan'ın mevcut aşamasında henüz uygulanmayan özellikler de dahil olmak üzere kapsamlı bir görünüm sunulmaktadır. Bu gibi durumlarda zaman çizelgesi rehberliği sağlanır.

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

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 renkle daire içine alınmış) paralel olarak çalışılabilir. Örneğin, iş ortağı etkileşimi, uygulamadan uygulamaya etkinlik düzeyinde ilişkilendirme ile aynı anda yapılabilir.

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

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

Ön koşullar ve kurulum

İlişkilendirme Raporlama API'sini daha iyi anlamak için bu bölümdeki adımları tamamlayın. Bu adımlar, API'yi reklam teknolojisi ekosisteminde kullanırken anlamlı sonuçlar elde etmenizi sağlar.

API'yi tanıma

  1. Attribution Reporting API ve özellikleri hakkında bilgi edinmek için tasarım teklifini okuyun.
  2. Kullanım alanlarınız için ihtiyaç duyacağınız kodu ve API çağrılarını nasıl dahil edeceğinizi öğrenmek üzere 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 sunulan yeni özelliklerden haberdar olabilirsiniz.

Örnek uygulamayı ayarlama ve test etme

  1. Entegrasyonunuzu başlatmaya hazır olduğunuzda Android Studio'daki en son geliştirici önizlemesini kullanın.
  2. Etkinlik kayıtları ve rapor yayınlama işlemleri için örnek sunucu uç noktaları oluşturun. İnternette bulunan araçlarla birlikte kullanabileceğiniz sahte içerikler sağladık.
  3. Kaynak 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ün, 7 gün veya 2 ila 30 gün arasında özel bir döneme ait aralıkları destekler.
    2. Örnek uygulamayı çalıştırıp kullanarak kaynakları ve tetikleyicileri kaydettikten ve ayarlanan süre geçtikten sonra, etkinlik düzeyinde bir rapor ve şifrelenmiş toplu hale getirilebilir bir rapor aldığınızı doğrulayın. Raporlarda hata ayıklama yapmanız gerekiyorsa raporlama işlerini zorla çalıştırarak raporları daha hızlı oluşturabilirsiniz.
    3. Uygulamadan uygulamaya ilişkilendirmeyle ilgili sonuçları inceleyin. Bu sonuçlardaki verilerin hem son dokunma hem de yükleme sonrası durumlar için beklendiği gibi olduğunu onaylayın.

  4. İstemci API'sinin ve 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 şekilde kopyalanmasını önlemek için tasarlanmıştır. Bu kopyalama, kullanıcının etkinlikleri hakkında gerekenden daha fazla bilgiye erişilmesine olanak tanı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ı olmak için hazırlanmanıza yardımcı olur.

  1. Attribution Reporting API'nin test edilmesi ve benimsenmesi hakkında konuşmak 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ı, STP'ler, DSP'ler, reklamverenler veya şu anda birlikte çalıştığınız ya da birlikte çalışmak istediğiniz diğer iş ortakları yer alabilir.
  2. İlk testten kullanıma kadar entegrasyon zaman çizelgelerini belirlemek için ölçüm iş ortaklarınızla birlikte çalışın.
  3. İlişkilendirme tasarımında her ikinizin de hangi alanları kapsayacağınızı ölçüm iş ortaklarınızla açıklayın.
  4. Zaman çizelgeleri ve uçtan uca test 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ı, tetikleyicileri Attribution Reporting API'ye nasıl kaydeder?
    • 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ı arasında paylaşılması gereken raporlar var mı?
    • İş ortakları arasında başka entegrasyon noktaları veya uyumlulaştırma gerekiyor mu? Örneğin, iş ortaklarınızla birlikte dönüşümleri tekilleştirme üzerinde mi çalışmanız gerekiyor yoksa toplama anahtarlarını mı uyumlu hale getirmeniz gerekiyor?
  6. Uygulamadan web'e ilişkilendirme geçerliyse Attribution Reporting API'nin tasarımını, testini ve benimsenmesini görüşmek 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 soruları referans olarak kullanı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 uygulamadan uygulamaya ilişkilendirme ayarlamanıza yardımcı olur. Toplama sunucusu ilişkilendirmesinin prototipini oluşturmaya başlamadan önce bu bölümü tamamlamanız gerekir.

  1. Etkinlik kayıtları için bir toplama sunucusu ayarlayın. Bu işlemi, sağladığınız spesifikasyonu kullanarak sahte bir sunucu oluşturarak veya örnek sunucu kodunu kullanarak kendi sunucunuzu kurarak yapabilirsiniz.
  2. Reklamlar gösterilirken SDK'nıza veya uygulamanıza kaynak etkinliği çağrıları kaydettirme işlevini ekleyin.
    • Kritik hususlar şunlardır:
      • Kaynak etkinlik kimliklerinin kullanılabilir olduğundan ve kaynak kayıt API çağrılarına doğru şekilde iletildiğinden emin olun.
      • Tıklama kaynaklarını kaydetmek için bir "InputEvent" de iletebildiğ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ülemelere kıyasla tıklamalar gibi yüksek değerli kabul edilen etkinliklere yüksek öncelik atayın.
      • Süre sonu için varsayılan değer, test için UYGUN'dur. Alternatif olarak farklı süre sonu dönemleri yapılandırılabilir.
      • Filtreler ve ilişkilendirme aralıkları, test için varsayılan olarak bırakılabilir.
    • İsteğe bağlı olarak dikkate alabileceğiniz 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 tetikleyici etkinlik kaydetme işlevini ekleyin.
    • Kritik hususlar şunlardır:
    • İsteğe bağlı olarak dikkate alabileceğiniz noktalar şunlardır:
      • Doğruluk testleri yapana kadar tekilleştirme anahtarı oluşturmayı atlayın.
      • Simülasyon test 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.
      • Tetikleyici önceliği, test için gerekli değildir.
      • İlk test için filtreler 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 yol açıp açmadığı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österilmektedir. Bu sayede, entegrasyonunuzu tamamlamadan önce etki testine başlayabilirsiniz.

Test, sahip olduğunuz geçmiş dönüşüm kayıtlarına göre etkinlik ve toplanabilir raporların oluşturulmasının simüle edilmesi ve ardından simüle edilmiş bir toplama sunucusundan toplanmış sonuçların alınmasıyla 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 raporlarda 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ülasyonu Kitaplığı'nı oluşturun.
  2. Dönüşüm verilerinizin, simüle edilmiş rapor oluşturucuyla uyumlu olması için nasıl biçimlendirilmesi gerektiğiyle ilgili özelliği okuyun.
  3. Toplama anahtarlarınızı işletme gereksinimlerine göre tasarlayın.
    • Kritik hususlar şunlardır:
      • Müşterilerinizin veya iş ortaklarınızın toplama yapması gereken kritik boyutları göz önünde bulundurun ve değerlendirmenizi bunlara odaklayın.
      • İhtiyaçlarınız için gereken minimum toplama boyutu ve kardinalite sayısını belirleyin.
      • Kaynak ve tetikleyici taraflı anahtar parçalarının 128 biti aşmadığından emin olun.
      • Çözümleriniz, tetikleyici etkinlik başına birden fazla değere katkıda bulunmayı içeriyorsa değerleri maksimum katkı bütçesine (L1) göre ölçeklendirdiğinizden emin olun. Bu, gürültünün etkisini en aza indirmenize yardımcı olur.
      • Kampanya düzeyinde toplu dönüşüm sayılarını ve coğrafi düzeyde toplu satın alma değerlerini toplamak için bir anahtar ayarlamayla ilgili ayrıntıları içeren bir örnek aşağıda verilmiştir.
  4. Etkinlik ve toplanabilir raporlar oluşturmak için rapor oluşturucuyu çalıştırın.
  5. Özet raporlar almak için birleştirilebilir raporları simüle edilmiş toplama sunucuları üzerinden çalıştırın.
  6. Fayda denemeleri yapın:
    • Dönüşüm raporlamasının 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 temsili bir kısmında ç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 verilerine dayalı modellerle karşılaştırın.
    • Farklı gruplandırma stratejilerini deneyin ve bunların sonuçlarınızı nasıl etkilediğini görün.
      • Kritik hususlar arasında şunlar yer alır:
      • Teklifleri ayarlamayla ilgili özet raporların zamanında sunulması.
      • Cihazda ilişkilendirilebilir etkinliklerin ortalama sıklıkları. Örneğin, geçmiş satın alma etkinliği verilerine göre geri gelen etkin olmayan kullanıcılar.
      • Gürültü seviyesi. Daha fazla paket, daha küçük toplama anlamına gelir ve daha küçük toplama, daha fazla gürültü uygulanması anlamına gelir.

Prototip toplama sunucusu ilişkilendirmesi: Kurulum

Bu adımlar, kaynağınız ve tetikleyici etkinliklerinizle ilgili toplu raporlar almanızı sağlar.

  1. Toplama sunucunuzu ayarlayın:
    • AWS hesabınızı oluşturun.
    • Koordinatörünüzle birlikte toplama hizmetine kaydolun.
    • Sağlanan ikili dosyalardan AWS'de toplama sunucunuzu ayarlayın.
  2. Toplama anahtarlarınızı işletme gereksinimlerine göre tasarlayın. Bu görevi uygulamadan uygulamaya etkinlik düzeyinde bölümde zaten tamamladıysanız bu adımı atlayabilirsiniz.
  3. Toplanabilir raporlar için bir koleksiyon sunucusu oluşturun. Uygulama-uygulama etkinlik düzeyi bölümünde daha önce bir tane oluşturduysanız bunu 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 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 durumda, toplama anahtarına dahil edilmek üzere reklam etkinliğiyle ilgili daha fazla verinin (ör. kampanya kimliği) SDK'nıza veya uygulamanıza aktarılması gerekebilir.
  2. Kaynaktan uygulamadan uygulamaya toplanabilir raporlar toplayın ve toplama anahtarı verileriyle kaydettiğiniz etkinlikleri tetikleyin.
  3. Toplama sunucusu üzerinden bu toplanabilir raporları çalıştırırken farklı gruplandırma stratejilerini test edin ve bunların sonuçlarınızı nasıl etkilediğini görün.

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

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

  1. Hata ayıklama anahtarı ayarlamak, Attribution Reporting API tarafından oluşturulan raporlarla birlikte bir kaynak veya tetikleyici etkinliğinin değiştirilmemiş raporunu almanıza olanak tanır. Raporları karşılaştırmak ve entegrasyon sırasında 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, daha yakın zamanda gerçekleşen başka uygun ilişkilendirme kaynakları olsa bile yükleme sonrası tetikleyicilerin yüklemeyi sağlayan aynı ilişkilendirme kaynağıyla ilişkilendirilmesi gerektiğinde kullanılabilir.
    • Örneğin, bir kullanıcının yükleme sağlayan bir reklamı tıkladığı durumlar olabilir. Uygulama yüklendikten sonra kullanıcı başka bir reklamı tıklar ve 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 ince ayar yapmak için filtreleri kullanın
    • Dönüşüm filtreleri, seçili tetikleyicileri yoksayacak ve etkinlik raporlarından hariç tutacak şekilde ayarlanabilir. İlişkilendirme kaynağı başına tetikleyici sayısıyla ilgili sınırlamalar olduğundan filtreler, etkinlik raporlarınıza 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 filtrelemek isteyebilirsiniz.
    • Filtreler, tetikleyici verilerini kaynak verilere göre özelleştirmek için de kullanılabilir. Örneğin, bir kaynakta "product" : ["1234"] belirtilebilir. Burada product filtre anahtarı, 1234 ise değerdir. "product" filtre anahtarına sahip ve "1234" dışında bir değere sahip tüm tetikleyiciler yoksayılır.
  3. Özelleştirilmiş kaynak ve tetikleyici önceliği
    • Birden fazla ilişkilendirme kaynağının bir tetikleyiciyle ilişkilendirilebildiği veya birden fazla tetikleyicinin bir kaynakla ilişkilendirilebildiği durumlarda, belirli kaynak/tetikleyici ilişkilendirmelerine diğerlerine göre öncelik vermek için imzalı 64 bit tam sayı kullanabilirsiniz.

MMP'ler ve diğer satıcılarla çalışma

  1. Kaynak ve tetikleyici etkinlikler için diğer üçüncü taraflara yönlendirmeler
    • Yönlendirme URL'lerini, birden fazla reklam teknolojisi platformunun istek 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ın anlamını açıklığa kavuşturmak için tekilleştirme anahtarı kullanılabilir. Tekilleştirme anahtarı sağlanmazsa yinelenen tetikleyiciler her reklam teknolojisi platformuna benzersiz olarak raporlanabilir.

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

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