Teklif verme adaptörü geliştirme

Bu kılavuz, Google uyumlulaştırmasında gerçek zamanlı teklif (GZT) özelliğine katılmak için 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ı aracılığı talimatlarını inceleyin.

Teklifli sistem bağdaştırıcısı, entegrasyonun istemci tarafı bölümüdür. Adaptör, 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.

Teklifli sistemin 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ü etkinliklerini iletme işlemlerini gerçekleştirmesi gerekir. Bu kılavuzda, bağdaştırıcınızın bu işlemleri gerçekleştirecek şekilde nasıl uygulanması gerektiği açıklanmaktadır.

Teklif verme adaptörü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österilmektedir:

Adaptör, iş akışının aşağıdaki kısımlarından sorumludur:

  • 4-7. adımlar: Adaptörünüzü başlatın ve başlatma işlemi tamamlandıktan sonra Google Mobile Ads SDK'sını geri çağırın.

  • 10-13. adımlar: Bir GZT isteğine katılmak için teklif vereninize gönderilecek reklam ağı SDK'nızdan sinyaller toplayın ve bunları Google Mobile Ads SDK'sına iletin.

  • 18-21. adımlar: Teklif vereniniz kazanan teklifi döndürürse reklamı teklif vereninizden gelen yanıta 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österilirken 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ü sırasında gerçekleşen diğer reklam etkinlikleri hakkında bilgilendirin.

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

Google Mobile Ads SDK'sı için teklif verme bağdaştırıcısı oluşturmak üzere RtbAdapter abstract sınıfını genişletmeniz gerekir. Aşağıdaki bölümlerde, RtbAdapter içindeki her bir 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 vereninize iletilir.

Bu yöntem için VersionInfo iade etmeniz gerekir. Aşağıdaki örnekte, SDK'nızın dize sürümünü nasıl VersionInfo.

@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 adaptörünüzün sürümünü döndürmeniz gerekir. Bu sürüm, OpenRTB isteğinin bir parçası olarak teklif vereninize iletilir.

Google'ın açık kaynaklı ve sürümlendirilmiş adaptörleri 4 haneli bir adaptör sürümü şeması kullanır ancak VersionInfo yalnızca 3 haneye izin verir. Bu sorunu çözmek için aşağıdaki örnekte gösterildiği gibi son iki rakamı yama sürümünde 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. Oturum başına yalnızca bir kez çağrılır. Bu yöntem, reklam ağınız için yapılandırılmış bu uygulamadaki yerleşimlerin tam listesini temsil eden MediationConfiguration nesnelerinin bir listesini sağlar. Her yerleşimin kimlik bilgilerini ayrıştırmak için bu listede döngü oluşturabilir ve başlatma için ilgili verileri SDK'nıza iletebilirsiniz.

SDK'nız ilk kullanıma hazır hale getirilip reklam isteklerini almaya hazır olduğunda onInitializationSucceeded() yöntemini çağırın.InitializationCompleteCallback Bu geri çağırma, uygulama yayıncılarına iletilir. Böylece yayıncılar reklam yüklemeye başlayabileceklerini bilir.

@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ılır. collectSignals() yöntemi, bağdaştırıcınızın cihazdan gelen ve OpenRTB isteğinde teklif vereninize gönderilecek sinyaller sağlamasına olanak tanır.

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

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

Burada bir örnek uygulama görebilirsiniz:

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

Adaptörünüz sinyal toplamayı başaramazsa signalCallbacks.onFailure() numaralı telefonu arayarak oluşan hatayı açıklayan bir dize iletin.

Reklam yükleme yöntemlerini uygulama

Zaman aşımı: 10 saniye

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

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

Reklam Biçimi Yükleme yöntemi
Banner loadBannerAd()
Geçiş reklamı loadInterstitialAd()
Ödüllü loadRewardedAd()

Adaptörünüzün desteklediği reklam biçimleri için bu yöntemleri uygulayın.

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

  • MediationAdConfiguration. Bu, SDK'nızın kazanan teklif için reklamı yüklemek üzere ihtiyaç duyduğu parametreleri (ör. teklif yanıtı ve yayıncının AdMob kullanıcı arayüzünde yapılandırdığı tüm kimlik bilgileri) içerir.

  • Yükleme başarılı olduğunda 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() işlevini çağırın. Etkinlik reklamı yükleme işlemi başarısız olursa mediationAdLoadCallback.onFailure() işlevini, oluşan hatayı açıklayan bir dizeyle çağırın.

mediationAdLoadCallback.onSuccess() yöntemi, Google Mobile Ads SDK'sı tarafından tanımlanan "Ad" arayüzlerinden birine uygun bir nesne iletmenizi gerektirir. Bu reklam arayüzlerinde reklamla ilgili bazı bilgiler vermeniz istenir.

MediationAdConfiguration, PNG resmini temsil eden base64 kodlu bir dize döndürmek için getWatermark() yöntemine de sahiptir. Bu resim, reklamlarınızda şeffaf bir yer paylaşımı olarak döşenmelidir. Filigranın nasıl oluşturulacağı hakkında daha fazla bilgi için Google ile iletişime geçin. Gösterilen reklamla ilgili meta veriler içerir. Yayıncılar, gösterilen reklamların kaynağını belirlemek için bu meta verileri kullanır.

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

Aşağıda, loadBannerAd() için örnek bir uygulama verilmiştir. Adaptörünüz farklı bir SDK ile entegre olduğundan adaptörünüzün uygulanması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 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ü etkinliklerini aktarma

Adaptörün nihai sorumluluğu, Google Mobile Ads SDK'sını tüm sunum yaşam döngüsü etkinlikleri hakkında bilgilendirmektir. Böylece bu etkinlikler yayıncıya iletilebilir. Yayıncı, hangi reklam ağının reklam sunduğundan bağımsız olarak bu geri çağırmaların belirli zamanlarda yapılmasını bekler. Bu nedenle, Google Mobile Ads SDK'sının bunları yayıncıya iletebilmesi için bu geri çağırmaların mümkün olduğunca çok sayıda ve doğru zamanda yapılması önemlidir.

Adaptörler, geçerli olduğunda aşağıdaki etkinlikleri çağırmalıdır:

Tüm biçimlerde ortaktır.
Yöntem Ne zaman aranır?
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 aramaları (ödüllü ve doğal reklamlar)
onVideoStarted() Reklamın videosu başlatıldı.
onVideoCompleted() Reklamın videosu tamamlandı.

Bağdaştırıcı, mediationAdLoadCallback.onSuccess() çağrıldığında MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> nesnesini geri alır. Adaptörlerin bu nesneyi tutması ve reklamınızda gerçekleşen sunum etkinliklerini çağırmak için kullanması beklenir.

Genellikle bu etkinliklerin çoğu reklam ağınızın SDK'sı tarafından yönlendirilir. Bağdaştırıcının görevi, reklam ağı SDK'nızdaki geri çağırmaları Google Mobile Ads SDK'sına eşlemekten ibarettir.

Aşağıdaki örnek, SDK'nızın reklam dinleyicisinden gelen 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 izleme 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ın geçerli bir gösterimin oluşturulması için belirli öğelerin gösterilmesini gerektiriyorsa teklif vereniniz, gerekli bu doğal öğeleri teklif yanıtında belirtebilir. Ardından Google Mobile Ads SDK'sı, bir gösterim kaydedilmeden önce gerekli yerel öğelerinizin gösterildiğini doğrular.

Teklif yanıtında ek zorunlu öğelerin nasıl belirtileceği hakkında daha fazla bilgi için yerel zorunlu öğelerle ilgili dokümanlara bakın.

Reklam hatalarını göster

Geçiş reklamları ve ödüllü reklamlar gibi tam ekran biçimlerinde, yükleme başarılı olduğunda geri çağırma işlevinde 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ı reklamı başarıyla yüklediyse yayıncı göstermesini istediğinde reklamın gösterilmeye hazır olduğunu varsayar. Bu, her gösterim çağrısının bir gösterimle sonuçlanması gerektiği anlamına gelir.

Ancak, reklam gösteremeyeceğiniz bazı özel durumlar olabilir. Reklamı gösteremiyorsanız gösterimi iptal etmek için onAdFailedToShow() geri arama işlevini kullanın.

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

Geri Arama Sonuç
onAdOpened() Impression recorded
onAdFailedToShow() Impression failure1
Yukarıdakilerin hiçbiri birkaç saniye boyunca Impression recorded

1 Başarısız gösterimler için reklam ağınızdan gösterim ücreti alınmaz ancak bu durum, faturalandırılabilir etkinlik oranı ayarınızı etkiler. Daha fazla bilgi için teklif isteği sinyallerine göz atın.

Aşağıdaki sahte örnekte, bir reklam gösterme çağrısının başarısızlıkla 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, ...);
  }
}