Teklif verme adaptörü geliştirme

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

Teklif bağdaştırıcısı, entegrasyonun istemci tarafındaki kısmı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 (Legacy) ile iletişim kurmasını sağlar.

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

Teklifli sistem 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:

Adaptör, iş akışının aşağıdaki bölümlerinden sorumludur:

• 4-7. adımlar: Adaptörünüzü başlatın ve başlatma işlemi tamamlandıktan sonra Google Mobile Ads SDK (Legacy) 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 vereninizden gelen yanıta göre yükleyin. Yüklendikten sonra Google Mobile Ads SDK (Legacy) adlı reklamverene 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.

Teklifli sistem bağdaştırıcısını uygulama

Google Mobile Ads SDK (Legacy) 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 sınıfındaki 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, VersionInfo döndürmenizi gerektirir. 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 bağdaştırıcı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ü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 haneye izin verir. Bu sorunu çözmek için son iki basamağı aşağıda gösterildiği gibi 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, bu uygulamada reklam ağınız için yapılandırılmış yerleşimlerin tam listesini temsil eden MediationConfiguration nesnelerinin listesini sağlar. Her yerleşimin kimlik bilgilerini ayrıştırmak ve başlatma için ilgili verileri SDK'nıza iletmek üzere bu listede döngü oluşturabilirsiniz.

SDK'nız başlatılıp reklam isteklerini almaya hazır olduğunda 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 öğenizin yeni bir örneği oluşturulur ve collectSignals() yöntemi çağrılır. RtbAdapter örneği, reklam isteği, yanıt ve reklamın oluşturma yaşam döngüsü boyunca kullanılır. collectSignals() yöntemi, adaptörünüzün cihazdan sinyaller sağlayarak OpenRTB isteğinde teklif vereninize gönderilmesini sağlar.

collectSignals(), arka plan iş parçacığında çağrılır. Google Mobile Ads SDK (Legacy) teklifli sisteme 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ü 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şler initialize() yönteminde yapılmalı ve önbelleğe alınmalıdır.

Sinyalleriniz hazır olduğunda kodlanmış sinyallerinizle onSuccess() geri çağırma 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 oluşan hatayı açıklayan bir dizeyle signalCallbacks.onFailure() yöntemini ç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 (Legacy), 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 yükleme yöntemi, bu isteğin hangi reklam biçimi için olduğuna bağlıdır:

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ının aynı örneğinde, kullanıcı arayüzü iş parçacığında çağrılır. Bu yöntem size aşağıdaki parametreleri sağlar:

• Kazanan teklif için SDK'nızın 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 (Legacy) nesnesini bilgilendirmek için kullanılan bir MediationAdLoadCallback nesnesi.

SDK'nız reklamı yükledikten sonra mediationAdLoadCallback.onSuccess() yöntemini çağırın. Reklam yükleme başarısız olursa oluşan hatayı açıklayan bir dizeyle mediationAdLoadCallback.onFailure() yöntemini çağırı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 vermenizi ister.

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

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 sonra göstermek üzere bir show() yöntemi uygulamanız istenir. En iyi uygulama olarak, reklam yükleme işlemini gerçekleştiren 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 edildiğinden adaptörü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 Google Mobile Ads SDK (Legacy).
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

Adaptörün son sorumluluğu, yayıncıya iletilebilmeleri için tüm sunum yaşam döngüsü olaylarını Google Mobile Ads SDK (Legacy)'a bildirmektir. Yayıncı, reklamı hangi reklam ağının yayınladığına bakılmaksızın bu geri çağırmaları belirli zamanlarda bekler. Bu nedenle, Google Mobile Ads SDK (Legacy) tarafından yayıncıya iletilebilmeleri için bu geri çağırmaların mümkün olduğunca fazlasının doğru zamanda çağrılması önemlidir.

Uygun olduğunda bağdaştırıcılar aşağıdaki etkinlikleri çağırmalıdır:

Bağdaştırıcı, mediationAdLoadCallback.onSuccess() çağrıldığında bir MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> nesnesi alır. Bağdaştırıcıların 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 tetiklenir. Bağdaştırıcının rolü, reklam ağı SDK'nızdan gelen geri çağırmaları Google Mobile Ads SDK (Legacy) ile eşlemektir.

Aşağıdaki örnekte, SDK'nızın reklam dinleyicisinden gelen geri çağırmaları Google Mobile Ads SDK (Legacy) öğesine nasıl yönlendireceğ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();
        }
    }
});

Doğal reklam gösterimi izleme için gerekli öğeler

Google Mobile Ads SDK (Legacy), reklamın 1 pikseli göründüğünde doğal 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 yerel öğeleri belirtebilir. Google Mobile Ads SDK (Legacy), gösterim kaydedilmeden önce gerekli doğal öğelerinizin gösterildiğini doğrular.

Teklif yanıtında ek zorunlu öğelerin nasıl belirtileceği hakkında daha fazla bilgi için doğal reklamlar için zorunlu öğelerle ilgili belgelere bakın.

Reklam hatalarını göster

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

Google Mobile Ads SDK (Legacy), bir bağdaştırıcı bir reklamı başarıyla yüklediyse yayıncı göstermek istediğinde reklamın gösterilmeye hazır olmasını bekler. Bu, her gösterim çağrısının bir gösterimle sonuçlanması gerektiği anlamına gelir.

Ancak reklam gösteremediğiniz uç durumlar olabilir. Reklamı gösteremiyorsanız gösterimi 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:

¹ 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ı düzenlemenizi etkiler. Daha fazla bilgi için teklif isteği sinyalleri bölümüne bakın.

Aşağıdaki örnekte, 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, ...);
  }
}