Teklif adaptörü geliştirme

Bu kılavuz, Google uyumlulaştırmasında gerçek zamanlı teklif vermeye (GZT) katılmak amacıyla teklif bağdaştırıcısı oluşturmak isteyen reklam ağları için hazırlanmıştır. Yayıncıysanız yayıncı uyumlulaştırması talimatlarını inceleyin.

Teklif bağdaştırıcısı, entegrasyonun istemci tarafı bölümüdür. Bağdaştırıcı, teklif vereniniz tarafından sunulan reklamları yüklemek için reklam ağı SDK'nızın Google Mobile Ads SDK'sı ile iletişim kurmasını sağlar.

Teklifin doğru çalışması için bağdaştırıcınızın başlatma, sinyal toplama, reklam yükleme ve reklam yaşam döngüsü olaylarını aktarma işlemlerini halletmesi gerekir. Bu kılavuzda, bu işlemleri yapmak için adaptörünüzün nasıl uygulanması gerektiğini adım adım göstereceğiz.

Not: Teklifli sisteme katılım için OpenRTB isteklerine yanıt verebilen bir teklif veren de gerekir. Teklif verenlerin nasıl karşılanacağına ilişkin talimatlar, bu kılavuzun kapsamı dışındadır.

Teklif bağdaştırıcısının iş akışı

Başlatma

Bir bağdaştırıcının tüm istek-yanıt oluşturma yaşam döngüsünün ayrıntılı akışı aşağıda gösterilmiştir:

Bağdaştırıcı, iş akışının aşağıdaki bölümlerinden sorumludur:

• 4.-7. adımlar: Bağdaştırıcınızı başlatın ve başlatma işlemi tamamlandığında Google Mobile Ads SDK'sını geri çağırın.

• 10-13. adımlar: Reklam ağı SDK'nızdan, GZT isteğine katılmak üzere teklif verene gönderilecek sinyalleri toplayın ve Google Mobile Ads SDK'sına yönlendirin.

• 18-21. Adımlar: Teklif vereniniz kazanan teklifi iade ederse reklamı teklif vereninizin yanıtına göre yükleyin. Yüklendikten sonra, Google Mobile Ads SDK'sına reklamın yüklendiğini bildirin.

• 23. Adım ve sonrası: Reklamınız görüntülenirken, Google Mobile Ads SDK'sını gösterim ve tıklama etkinliklerinin yanı sıra reklamınızın sunum yaşam döngüsü boyunca meydana gelen diğer reklam etkinlikleri hakkında da bilgilendirin.

Not: Google Mobile Ads SDK'sı, gösterim etkinliklerini ayrı olarak izler. Ancak tutarsızlıkları kontrol edebilmemiz için reklam ağınızın gösterim etkinliğini yönlendirmeniz de önemlidir.

Teklif bağdaştırıcısını uygulama

Google Mobile Ads SDK'sı için teklif bağdaştırıcısı oluşturmak istiyorsanız RtbAdapter soyut sınıfını genişletmeniz gerekir. Aşağıdaki bölümlerde RtbAdapter öğesindeki her soyut yöntem açıklanmaktadır.

getSDKVersionInfo()

Burada SDK'nızın sürümünü döndürmeniz gerekir. Bu sürüm, OpenRTB isteğinin bir parçası olarak teklif verene iletilir.

Bu yöntem, bir VersionInfo döndürmenizi gerektirir. Aşağıdaki örnekte, SDK'nızın dize sürümünü bir VersionInfo. parametresine nasıl

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

Burada bağdaştırıcınızın sürümünü görebilirsiniz. Bu sürüm, OpenRTB isteğinin bir parçası olarak teklif verene iletilir.

Google'ın açık kaynak ve sürümlü bağdaştırıcıları, 4 haneli bir bağdaştırıcı sürümü şeması kullanır ancak VersionInfo yalnızca 3 haneli değerlere izin verir. Bu sorunu çözmek için son iki basamağı aşağıda gösterildiği gibi yama sürümüyle birleştirmeniz önerilir.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

Zaman aşımı: 30 saniye

initialize() yöntemi, bağdaştırıcınızda çağrılan ilk yöntemdir. Bu işlev, oturum başına yalnızca bir kez çağrılır. Bu yöntemde, bu uygulamada reklam ağınız için yapılandırılmış yerleşimlerin tam listesini temsil eden MediationConfiguration nesnelerinin bir listesi sunulur. Her yerleşimin kimlik bilgilerini ayrıştırmak ve başlatma için ilgili verileri SDK'nıza iletmek için bu liste içinde döngü yapabilirsiniz.

SDK'nız başlatıldıktan ve reklam isteklerini almaya hazır hale geldikten sonra InitializationCompleteCallback için onInitializationSucceeded() yöntemini çağırın. Bu geri çağırma, reklam yüklemeye başlayabileceklerini bilmeleri için uygulama yayıncılarına yönlendirilir.

Not: initialize() yöntemi, bağdaştırıcının eskimiş bir örneğinde çağrılır. Bu örnekte başka hiçbir yöntem çağrılmaz. Bu yöntem sonucunda adaptörünüzün durumu kaydetmesi gerekirse tüm durumlar statik olmalıdır.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

Zaman aşımı: 1 saniye

Yayıncı her reklam isteğinde bulunduğunda RtbAdapter öğenizin yeni bir örneği oluşturulur ve collectSignals() yöntemi çağrılır. Bu RtbAdapter örneği, söz konusu reklam için reklam isteği, yanıt ve oluşturma yaşam döngüsü boyunca kullanılacaktır. collectSignals() yöntemi, bağdaştırıcınızın bir OpenRTB isteğinde teklif verene gönderilecek ve cihazdan gelen sinyaller sağlamasına olanak tanır.

collectSignals(), arka plandaki bir ileti dizisinde çağrılır. Google Mobile Ads SDK'sı aynı anda teklifli sisteme katılan tüm bağdaştırıcılardan sinyal ister. Lütfen saygılı olun ve bu süre zarfında kullanıcı arayüzü iş parçacığına yapılan çağrıları sınırlayın. Sinyalleri toplamak için bağdaştırıcınızın veya SDK'nızın yapması gereken tüm yoğun çalışmalar initialize() yönteminde yapılmalı ve önbelleğe alınmalıdır.

Sinyalleriniz hazır olduğunda, kodlanmış sinyallerinizle birlikte onSuccess() geri çağırmasını çağırın.

Aşağıda örnek bir uygulama verilmiştir:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

Bağdaştırıcınız sinyalleri toplamıyorsa oluşan hatayı açıklayan bir dizeyle signalCallbacks.onFailure() yöntemini çağırın.

Not: Sinyal dizesi herhangi bir nesneyi temsil edebilir ve düz JSON, Base64 olarak kodlanmış gibi herhangi bir biçimde veya seçtiğiniz başka bir şifreleme biçiminde olabilir. Sinyallerin ağınız dışında opak olmasını sağlamak için sinyalleri şifrelemeniz önerilir.

Reklam yükleme yöntemlerini uygulama

Zaman aşımı: 10 saniye

Teklif vereniniz kazanan teklifi döndürürse Google Mobile Ads SDK'sı, kazanan reklamı yüklemek için bağdaştırıcınızı çağırarak teklif vereninizin döndürdüğü ve SDK'nızın reklamı yüklemesi gereken tüm verileri size iletir.

Çağrılan tam yükleme yöntemi, bu isteğin şunlara yönelik reklam biçimine bağlıdır:

İlan Biçimi	Yükleme yöntemi
Banner	loadBannerAd()
Geçişli	loadInterstitialAd()
Ödül olarak verildi	loadRewardedAd()

Bu yöntemleri, bağdaştırıcınızın desteklediği reklam biçimleri için uygulayın.

Yükleme yöntemi, sinyalleri sağladığınız bağdaştırıcı örneğinde, kullanıcı arayüzü iş parçacığında çağrılır. Bu yöntem size aşağıdaki parametreleri sağlar:

• SDK'nızın kazanan teklif için reklamı yüklemesi gereken parametreleri (ör. teklif yanıtı ve yayıncının AdMob kullanıcı arayüzünde yapılandırdığı kimlik bilgileri) içeren bir MediationAdConfiguration.

• Yükleme başarılı veya başarısız olduğunda Google Mobile Ads SDK'sını bilgilendirmek için kullanılan bir MediationAdLoadCallback nesnesi.

SDK'nız reklamı yükledikten sonra mediationAdLoadCallback.onSuccess() çağrısı yapın. Reklam yükleme başarısız olduğunda, oluşan hatayı açıklayan bir dizeyle mediationAdLoadCallback.onFailure() çağrısı yapın.

mediationAdLoadCallback.onSuccess() yöntemi, Google Mobile Ads SDK'sı tarafından tanımlanan "Reklam" arayüzlerinden birini onaylayan bir nesne iletmenizi gerektirir. Bu reklam arayüzleri, reklamla ilgili bazı bilgiler sağlamanızı ister.

MediationAdConfiguration, bir PNG resmini temsil eden base64 kodlu bir dizeyi döndürmek için getWatermark() yöntemi de içerir. Bu resim, reklamlarınızda şeffaf bir yer paylaşımına yerleştirilmelidir. Filigranın nasıl oluşturulacağıyla ilgili daha fazla yardım için Google ile iletişime geçin. Raporda, gösterilen reklamların kaynağını belirlemek amacıyla yayıncılar tarafından kullanılmak üzere gösterilen reklamla ilgili meta verileri içerir.

Banner'lar için banner görünümünü sağlamanız istenir. Geçiş reklamları ve ödüllü reklamlarda, reklamı daha sonra göstermek için bir show() yöntemi uygulamanız istenir. En iyi uygulama olarak, reklam yüklemesini yapan sınıfınızı bu reklam yöntemlerini uygulamaktan da sorumlu hale getirmenizi öneririz.

Aşağıda, loadBannerAd() için örnek bir uygulama verilmiştir. Bağdaştırıcınız farklı bir SDK ile entegre olduğundan bağdaştırıcınızın uygulamasının farklı görüneceğini unutmayın.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to the Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

Reklam sunumu yaşam döngüsü olaylarını aktarma

Bağdaştırıcının son sorumluluğu, tüm sunum yaşam döngüsü olaylarını Google Mobile Ads SDK'sına bildirerek bunların yayıncıya iletilebilmesini sağlamaktır. Yayıncı, reklamı hangi reklam ağının sunduğundan bağımsız olarak belirli zamanlarda bu geri çağırmaları bekler. Bu nedenle, bu geri çağırmaların mümkün olduğunca çok sayıda ve doğru zamanda çağrılması, böylece Google Mobile Ads SDK'sının bunları yayıncıya iletebilmesi önemlidir.

Bağdaştırıcılar, uygun olduğunda aşağıdaki etkinlikleri çağırmalıdır:

Tüm formatlarda ortaktır
Yöntem	Arama zamanı
reportAdClicked()	Reklam tıklandı.
reportAdImpression()	Reklam bir gösterim oluşturdu.
onAdOpened()	Reklam, tam ekran görünümü sunuyordu.
onAdClosed()	Reklamın tam ekran görünümü kapatıldı.
onAdLeftApplication()	Reklam, kullanıcının uygulamadan ayrılmasına neden oldu.
Ödüllü reklamlar
onRewarded()	Kullanıcıya ödül verilir.
Video geri çağırmaları (ödüllü ve yerel reklamlar)
onVideoStarted()	Reklamın videosu başladı.
onVideoCompleted()	Reklamın videosu tamamlandı.

mediationAdLoadCallback.onSuccess() çağrısının ardından bağdaştırıcı, MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> nesnesini geri alıyor. Bağdaştırıcıların bu nesneyi tutması ve reklamınızda gerçekleşen sunu etkinliklerini çağırmak için kullanması beklenir.

Genellikle bu etkinliklerin çoğu reklam ağınızın SDK'sı tarafından yönetilir. Bağdaştırıcının rolü, reklam ağınız SDK'sından gelen geri çağırmaları Google Mobile Ads SDK'sına eşlemektir.

Aşağıdaki örnek, SDK'nızın reklam işleyicisinden geri çağırmaları Google Mobile Ads SDK'sına nasıl yönlendireceğinizi gösterir:

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

Yerel reklam gösterim izlemesi için gerekli öğeler

Google Mobile Ads SDK'sı, reklamın 1 pikseli görünür olduğunda yerel reklam için bir gösterim kaydeder. Reklam ağı SDK'nız geçerli bir gösterim oluşturmak için belirli öğelerin gösterilmesini gerektiriyorsa teklif vereniniz bu gerekli yerel öğeleri teklif yanıtında belirtebilir. Ardından Google Mobile Ads SDK'sı, gösterimi kaydetmeden önce gerekli yerel öğelerinizin görüntülendiğini doğrular.

Teklif yanıtında gerekli ek öğelerin nasıl belirtileceği hakkında daha fazla bilgi için yerel gerekli öğeler belgelerine bakın.

Önemli Nokta: Reklam ağınızdaki yerel gerekli ek öğeler nedeniyle geçersiz oluşturulan gösterimler, söz konusu yayıncı için faturalandırılabilir etkinlik oranınızı etkiler.

Reklam hatalarını göster

Geçiş reklamları ve ödüllü reklamlar gibi tam ekran biçimlerinde, başarı yüklemesi geri çağırmasında MediationInterstitialAd veya MediationRewardedAd uygulamasını sağlarsınız. Böylece Google Mobile Ads SDK'sı, bağdaştırıcınızdan reklamı göstermesini isteyebilir.

Google Mobile Ads SDK'sı, bir bağdaştırıcının bir reklamı başarıyla yüklemesi durumunda, yayıncı reklamı göstermek istediğinde reklamın gösterilmeye hazır olmasını bekler. Bu, her program çağrısının bir gösterimle sonuçlanacağı anlamına gelir.

Ancak, zaman zaman reklam gösteremeyebilirsiniz. Reklamı gösteremiyorsanız gösterimi iptal etmek için onAdFailedToShow() geri çağırmasını çağırın.

Aşağıdaki tabloda, sunu geri çağırmalarının tam ekran reklam biçimleri için gösterim kaydını nasıl etkilediği gösterilmektedir:

Geri Arama	Sonuç
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Birkaç saniye boyunca yukarıdakilerin hiçbiri	Impression recorded

¹ Başarısız gösterimlerde, reklam ağınızdan gösterim için ücret alınmaz ancak bu durum faturalandırılabilir etkinlik ücret ayarlamanızı etkiler. Daha fazla bilgi için teklif isteği sinyallerine bakın.

Aşağıdaki örnek örneğin, bir reklam gösterimi çağrısının hatayla sonuçlanabileceği bir yükleme/gösterme yaşam döngüsü gösterilmektedir.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}