Teklif verme adaptörü geliştirme

Bu kılavuz, Google uyumlulaştırması kapsamında gerçek zamanlı teklif vermeye (GZT) katılmak için teklifli sistem 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ırma talimatlarını inceleyin.

Teklifli sistem bağdaştırıcısı, entegrasyonun istemci tarafı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 düzgün çalışması için bağdaştırıcının ilk başlatma, sinyal toplama, reklam yükleme ve reklam yaşam döngüsü etkinliklerini aktarma işlemlerini yapması gerekir. Bu kılavuzda, bu işlemleri gerçekleştirmek için adaptörünüzün nasıl uygulanması gerektiği konusunda size yol göstereceğiz.

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

Başlatma

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

Uyumlulaştırma aracı, iş akışının aşağıdaki bölümlerinden sorumludur:

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

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

  • 18-21. adımlar: Teklif vereniniz kazanan teklifi döndürürse reklamı, teklif vereninizin yanıtına göre yükleyin. Yüklendikten sonra Google Mobile Ads SDK'sını reklamın yüklendiği konusunda bilgilendirin.

  • 23. adım ve sonraki adımlar: 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ı uygulama

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

Bu yöntem için VersionInfo cihazı iade etmeniz gerekir. Aşağıdaki örnekte, SDK'nızın dize sürümünü nasıl bir 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ü belirtmeniz gerekir. Bu sürüm, OpenRTB isteği kapsamında teklif vereninize iletilir.

Google'ın açık kaynak ve sürümlü adaptörleri 4 haneli bir adaptör sürümü şeması kullanır ancak VersionInfo yalnızca 3 haneye izin verir. Bu sorunu gidermek için aşağıdaki gibi son iki hanenin yama sürümüne eklenmesi ö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, adaptörünüzde çağrılan ilk yöntemdir. Oturum başına yalnızca bir kez çağrılır. Bu yöntem, bu uygulamadaki reklam ağınız için yapılandırılmış yerleşimlerin tam listesini temsil eden bir MediationConfiguration nesnesi listesi sağlar. Her yerleşimin kimlik bilgilerini ayrıştırmak ve ilgili verileri başlatma için SDK'nıza iletmek üzere bu listeyi döngü şeklinde inceleyebilirsiniz.

SDK'nız başlatıldıktan ve reklam isteği almaya hazır olduktan sonra InitializationCompleteCallback sınıfının 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.

@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 istediğinde RtbAdapter sınıfınızın yeni bir örneği oluşturulur ve collectSignals() yöntemi çağrılır. Bu RtbAdapter örneği, reklam isteği, yanıt ve söz konusu reklamın oluşturma yaşam döngüsü boyunca kullanılır. collectSignals() yöntemi, bağdaştırıcınızın OpenRTB isteğinde teklif vereninize gönderilecek cihaz sinyalleri sağlamasına olanak tanır.

collectSignals(), arka plan iş parçacığında çağrılır. Google Mobile Ads SDK'sı, teklif vermeye katılan tüm bağdaştırıcılardan aynı anda sinyal ister. Lütfen bu süre zarfında kullanıcı arayüzü ile ilgili mesaj dizisine gönderdiğiniz çağrıları sınırlandırın ve saygılı davranı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şler initialize() yönteminde yapılmalı ve önbelleğe alınmalıdır.

Sinyalleriniz hazır olduğunda, kodlanmış sinyallerinizi kullanarak onSuccess() geri arama işlevini çağırın.

Burada bir örnek uygulama görebilirsiniz:

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

Bağdaştırıcınız sinyal toplayamazsa meydana gelen hatayı açıklayan bir dizeyle signalCallbacks.onFailure() aramasına çağırın.

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ğırır ve teklif vereninizin döndürdüğü, SDK'nızın bu reklamı yüklemesi için ihtiyaç duyduğu tüm verileri size iletir.

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

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

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

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

  • SDK'nızın kazanan teklifin reklamını yüklemesi için ihtiyaç duyduğu 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ı 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. Reklam yükleme işlemi başarısız olduğunda, oluşan hatayı açıklayan bir dizeyle mediationAdLoadCallback.onFailure() işlevini çağırın.

mediationAdLoadCallback.onSuccess() yöntemi, Google Mobile Ads SDK'sı tarafından tanımlanan "Reklam" arayüzlerinden birine uygun bir nesne iletmenizi gerektirir. Bu reklam arayüzleri, reklam hakkında bazı bilgiler vermenizi ister.

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

Banner'lar için banner görünümünü sağlamanız istenir. Geçiş ve ödüllü reklamlar için reklamı daha sonra 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ün farklı bir SDK ile entegre olması nedeniyle adaptörünüzün uygulama şeklinin farklı olacağını 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ü etkinliklerini aktarma

Uyumlatıcının nihai sorumluluğu, tüm sunum yaşam döngüsü etkinliklerini Google Mobile Ads SDK'sına bildirmektir. Böylece bu etkinlikler yayıncıya yönlendirilebilir. Yayıncı, reklamı hangi reklam ağının yayınladığına bakılmaksızın 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ğırmalardan mümkün olduğunca çoğunun doğru zamanda çağrılması önemlidir.

Uyumlulaştırma araçları, geçerli olduğunda aşağıdaki etkinlikleri çağırmalıdır:

Tüm biçimler için ortak
Yöntem Ne zaman aramalısınız?
reportAdClicked() Reklam tıklandı.
reportAdImpression() Reklam bir gösterim oluşturdu.
onAdOpened() Reklam tam ekran görünümünde sunuluyordu.
onAdClosed() Reklamın tam ekran görünümü kapatıldı.
onAdLeftApplication() Reklam, kullanıcının uygulamadan çıkmasına neden oldu.
Ödüllü reklamlar
onRewarded() Kullanıcıya ödül verilir.
Video geri çağırma (ödüllü ve doğal reklamlar)
onVideoStarted() Reklamın videosu başladı.
onVideoCompleted() Reklamın videosu tamamlandı.

Adaptör, mediationAdLoadCallback.onSuccess() çağrıldıktan sonra bir MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> nesnesi alır. Adaptörlerin bu nesneyi tutması ve reklamınızda gerçekleşen sunum etkinliklerini çağırmak için kullanması beklenir.

Bu etkinliklerin çoğu genellikle reklam ağınızın SDK'sı tarafından yönlendirilir. Bağdaştırıcının rolü, reklam ağı SDK'nızdan gelen geri çağırma işlevlerini Google Mobile Ads SDK'sıyla eşlemektir.

Aşağıdaki örnekte, SDK'nızın reklam dinleyicisinden Google Mobile Ads SDK'sına geri çağırma çağrılarını nasıl ileteceğiniz gösterilmektedir:

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 piksellik kısmı 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, teklif yanıtında bu gerekli doğal öğeleri belirtebilir. Ardından Google Mobile Ads SDK'sı, gösterim kaydetmeden önce gerekli yerel öğelerinizin gösterilip gösterilmediğini doğrular.

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

Reklam hatalarını göster

Geçiş reklamı ve ödüllü reklam gibi tam ekran biçimler için, Google Mobile Ads SDK'sının bağdaştırıcınızdan reklamı göstermesini isteyebilmesi amacıyla, yükleme işleminin başarılı olduğu geri çağırma işlevinde MediationInterstitialAd veya MediationRewardedAd uygulamasını sağlarsınız.

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östermeyi istediğinde reklamın gösterilmeye hazır olmasını bekler. Bu, her bir gösterme çağrısının bir gösterimle sonuçlanması gerektiği anlamına gelir.

Ancak reklam gösteremediğiniz bazı durumlar olabilir. Reklamı gösteremiyorsanız görüntülemeyi iptal etmek için onAdFailedToShow() geri çağırma işlevini çağırın.

Aşağıdaki tabloda, sunum 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 failure1
Birkaç saniye boyunca yukarıdakilerin hiçbiri Impression recorded

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

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