Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie adaptera stawek

Ten przewodnik jest przeznaczony dla sieci reklamowych, które chcą utworzyć adapter określania stawek, aby uczestniczyć w określaniu stawek w czasie rzeczywistym (RTB) w ramach zapośredniczenia Google. Jeśli jesteś wydawcą, zapoznaj się z instrukcjami dotyczącymi zapośredniczenia dla wydawców.

Adapter ustalania stawek to element integracji po stronie klienta. Adapter umożliwia pakietowi SDK sieci reklamowej komunikację z pakietem SDK do reklam mobilnych Google w celu wczytywania reklam wyświetlanych przez licytującego.

Aby określanie stawek działało prawidłowo, adapter musi obsługiwać inicjowanie, zbieranie sygnałów, wczytywanie reklam i przekazywanie zdarzeń cyklu życia reklam. W tym przewodniku pokażemy, jak wdrożyć adapter, aby obsługiwała te operacje.

Przepływ pracy adaptera określania stawek

Zdarzenie inicjujące

Poniżej znajdziesz szczegółowy przebieg całego cyklu życia renderowania adaptera żądania i odpowiedzi:

Adapter odpowiada za te części przepływu pracy:

Kroki 4–7. Zainicjuj adapter i po zakończeniu inicjowania wywołaj zwrotny pakiet SDK do reklam mobilnych Google.
Kroki 10–13. Zbierz w pakiecie SDK sieci reklamowej sygnały, które będą wysyłane do systemu licytującego, aby wziąć udział w żądaniu RTB, i przekaż je do pakietu SDK do reklam mobilnych Google.
Kroki 18–21. Jeśli licytujący zwróci zwycięską stawkę, wczytaj reklamę zgodnie z odpowiedzią licytującego. Po załadowaniu reklamy powiadom pakiet SDK do reklam mobilnych Google, że reklama została załadowana.
Krok 23 i późniejsze: w czasie wyświetlania reklamy powiadamiaj pakiet SDK do reklam mobilnych Google o zdarzeniach wyświetlenia i kliknięcia oraz o innych zdarzeniach związanych z reklamą, które zaszły w trakcie jej cyklu życia.

Implementowanie adaptera ustalania stawek

Aby utworzyć adapter ustalania stawek na potrzeby pakietu SDK do reklam mobilnych Google, musisz rozszerzyć klasę abstrakcyjną RtbAdapter. W sekcjach poniżej objaśniamy poszczególne metody abstrakcyjne w języku RtbAdapter.

getSDKVersionInfo()

W tym miejscu należy zwrócić wersję pakietu SDK. Ta wersja jest przekazywana do licytującego w ramach żądania OpenRTB.

Ta metoda wymaga zwrotu elementu VersionInfo. Przykład poniżej pokazuje, jak przekonwertować wersję ciągu znaków pakietu SDK na 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()

W tym miejscu należy zwrócić wersję adaptera. Ta wersja jest przekazywana do licytującego w ramach żądania OpenRTB.

Przejściówki Google typu open source i wersjonowane używają 4-cyfrowego schematu wersji adaptera, ale VersionInfo umożliwia stosowanie tylko 3 cyfr. Aby obejść ten problem, zalecamy połączenie ostatnich 2 cyfr w wersji poprawki w sposób podany poniżej.

@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()

Czas oczekiwania: 30 sekund

Metoda initialize() jest pierwszą metodą wywoływaną w adapterze. Jest wywoływana tylko raz na sesję. Ta metoda generuje listę obiektów MediationConfiguration, które reprezentują pełną listę miejsc docelowych w tej aplikacji skonfigurowanych dla Twojej sieci reklamowej. Możesz zapętlić tę listę, aby przeanalizować dane logowania do każdego miejsca docelowego i przekazać odpowiednie dane do pakietu SDK na potrzeby inicjowania sieci.

Gdy pakiet SDK jest zainicjowany i będzie gotowy do odbierania żądań reklam, wywołaj metodę onInitializationSucceeded() interfejsu InitializationCompleteCallback. To wywołanie zwrotne jest przekazywane wydawcom aplikacji, aby wiedzieli, że mogą zacząć ładować reklamy.

@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()

Czas oczekiwania: 1 sekunda

Za każdym razem, gdy wydawca wysyła żądanie reklamy, tworzone jest nowe wystąpienie obiektu RtbAdapter i wywoływana jest metoda collectSignals(). Ta instancja RtbAdapter będzie używana podczas trwania cyklu życia żądania reklamy, odpowiedzi i renderowania tej reklamy. Metoda collectSignals() umożliwia adapterowi dostarczanie sygnałów z urządzenia, które są wysyłane do licytującego w żądaniu OpenRTB.

Wywołanie usługi collectSignals() w wątku w tle. Pakiet SDK do reklam mobilnych Google jednocześnie prosi o sygnały od wszystkich adapterów uczestniczących w określaniu stawek. Pamiętaj o szacunku i ogranicz liczbę wywołań do wątku UI w tym czasie. Wszelkie intensywne czynności, które musi wykonać adapter lub pakiet SDK, aby zbierać sygnały, należy wykonywać za pomocą metody initialize() i pamięci podręcznej.

Po przygotowaniu sygnałów wywołaj wywołanie zwrotne onSuccess(), podając zakodowane sygnały.

Oto przykładowa implementacja:

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

Jeśli adapter nie zbiera sygnałów, wywołaj funkcję signalCallbacks.onFailure(), podając ciąg znaków objaśniający wystąpienie błędu.

Stosowanie metod wczytywania reklam

Czas oczekiwania: 10 sekund

Jeśli licytujący zwróci zwycięską stawkę, pakiet SDK do reklam mobilnych Google wywoła adapter, aby wczytać zwycięską reklamę. W ten sposób dostarczysz wszystkie dane potrzebne do wczytania reklamy przez pakiet SDK.

Dokładna wywoływana metoda ładowania zależy od formatu reklamy, którego dotyczy to żądanie:

Format reklamy	Metoda ładowania
Baner	`loadBannerAd()`
Pełnoekranowa	`loadInterstitialAd()`
Otrzymano	`loadRewardedAd()`

Te metody możesz stosować w przypadku formatów reklam obsługiwanych przez adapter.

Metoda wczytywania jest wywoływana w wątku interfejsu użytkownika w tej samej instancji adaptera, z której pochodzą sygnały. Ta metoda udostępnia te parametry:

MediationAdConfiguration, który zawiera parametry potrzebne do wczytania reklamy dla zwycięskiej stawki, takie jak odpowiedź na stawkę i dane logowania skonfigurowane przez wydawcę w interfejsie AdMob.
Obiekt MediationAdLoadCallback używany do powiadamiania pakietu SDK do reklam mobilnych Google po pomyślnym lub nieudanym wczytaniu.

Gdy pakiet SDK wczyta reklamę, wywołaj mediationAdLoadCallback.onSuccess(). W przypadku wystąpienia błędu ładowania reklamy wywołaj zdarzenie mediationAdLoadCallback.onFailure(), podając ciąg znaków wyjaśniający zaistniały błąd.

Metoda mediationAdLoadCallback.onSuccess() wymaga przekazania obiektu, który potwierdza do jednego z interfejsów „Reklama” zdefiniowanych przez pakiet SDK do reklam mobilnych Google. W tych interfejsach musisz podać trochę informacji o reklamie.

MediationAdConfiguration ma też metodę getWatermark(), która zwraca ciąg zakodowany w standardzie base64 reprezentujący obraz PNG. Ten obraz powinien zostać ułożony w przezroczystą nakładkę na reklamy. Skontaktuj się z Google, aby uzyskać dodatkowe wskazówki dotyczące renderowania znaku wodnego. Zawiera on metadane dotyczące wyświetlanej reklamy, co pozwala wydawcom określić źródło wyświetlania reklam.

W przypadku banerów poprosimy Cię o włączenie widoku banera. W przypadku reklam pełnoekranowych i reklam z nagrodą poprosimy Cię o implementację metody show(), aby umożliwić ich późniejsze wyświetlanie. Zalecamy, aby klasa, która wczytuje reklamy, odpowiada za implementowanie tych metod reklamowych.

Poniżej znajdziesz przykładową implementację interfejsu loadBannerAd(). Pamiętaj, że implementacja adaptera będzie wyglądać inaczej, ponieważ jest on zintegrowany z innym pakietem SDK.

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;
  }
}

Zdarzenia cyklu życia prezentacji reklamy w przekaźniku

Ostatecznym obowiązkiem adaptera jest powiadamianie pakietu SDK do reklam mobilnych Google o każdym zdarzeniu cyklu życia prezentacji, aby można je było przekazać wydawcy. Wydawca oczekuje, że te wywołania zwrotne będą miały miejsce w określonych momentach, bez względu na to, która sieć reklamowa wyświetli reklamę. Dlatego ważne jest, by jak najwięcej z nich wywołano we właściwym czasie, tak by pakiet SDK do reklam mobilnych Google mógł przekazać je wydawcy.

Adaptery powinny w razie potrzeby wywoływać te zdarzenia:

Wspólny dla wszystkich formatów
Metoda	Kiedy zadzwonić
`reportAdClicked()`	Kliknięto reklamę.
`reportAdImpression()`	Reklama wygenerowała wyświetlenie.
`onAdOpened()`	Reklama wyświetliła się na pełnym ekranie.
`onAdClosed()`	Pełny ekran reklamy został zamknięty.
`onAdLeftApplication()`	Reklama spowodowała opuszczenie aplikacji przez użytkownika.
Reklamy z nagrodą
`onRewarded()`	Użytkownik otrzymuje nagrodę.
Wywołania zwrotne wideo (reklamy z nagrodą i reklamy natywne)
`onVideoStarted()`	Rozpoczął się film w reklamie.
`onVideoCompleted()`	Zakończono odtwarzanie filmu w reklamie.

Po wywołaniu mediationAdLoadCallback.onSuccess() adapter otrzymuje obiekt MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>. Adaptery mają przechowywać ten obiekt i wykorzystywać go do wywoływania zdarzeń prezentacji, które występują w reklamie.

Zwykle większość z tych zdarzeń jest wywoływana przez pakiet SDK sieci reklamowej. Rolą adaptera jest po prostu mapowanie wywołań zwrotnych z pakietu SDK sieci reklamowej na pakiet SDK do reklam mobilnych Google.

Poniższy przykład pokazuje, jak przekazywać wywołania zwrotne z odbiornika reklam z pakietu SDK do pakietu SDK do reklam mobilnych Google:

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();
        }
    }
});

Zasoby wymagane do śledzenia wyświetleń reklamy natywnej

Pakiet SDK do reklam mobilnych Google rejestruje wyświetlenie reklamy natywnej, gdy widoczny jest jeden piksel reklamy. Jeśli do poprawnego wyświetlenia pakiet SDK sieci reklamowej wymaga wyświetlenia określonych zasobów, system licytujący może wskazać te zasoby natywne w odpowiedzi na pytanie o stawkę. Następnie przed zarejestrowaniem wyświetlenia pakiet SDK do reklam mobilnych Google sprawdza, czy wyświetlają się wymagane zasoby natywne.

Więcej informacji o określaniu dodatkowych wymaganych komponentów w odpowiedzi na stawkę znajdziesz w dokumentacji zasobów natywnych.

Pokaż błędy reklamy

W przypadku formatów pełnoekranowych, np. reklam pełnoekranowych i reklam z nagrodą, podczas udanego wczytania wywołania zwrotnego musisz udostępnić implementację MediationInterstitialAd lub MediationRewardedAd , dzięki czemu pakiet SDK do reklam mobilnych Google może poprosić adaptera o wyświetlenie reklamy.

Pakiet SDK do reklam mobilnych Google oczekuje, że jeśli adapter pomyślnie załaduje reklamę, będzie ona gotowa do wyświetlenia, gdy wydawca poprosi o jej pokazanie. Oznacza to, że każde wywołanie programu powinno wiązać się z wyświetleniem.

Jednak w niektórych narożnych sytuacjach nie możesz wyświetlić reklamy. Jeśli nie możesz wyświetlić reklamy, wywołaj wywołanie onAdFailedToShow() , aby anulować wyświetlenie.

Tabela poniżej pokazuje, jak wywołania zwrotne prezentacji wpływają na rejestrowanie wyświetleń w przypadku formatów reklam pełnoekranowych:

Oddzwanianie	Wynik
onAdOpened()	`Impression recorded`
onAdFailedToShow()	`Impression failure¹`
Żadna z tych odpowiedzi nie występuje dłużej niż kilka sekund	`Impression recorded`

¹ W przypadku nieudanych wyświetleń sieć reklamowa nie nalicza opłat za wyświetlenie, ale wpływa to na korektę liczby zdarzeń podlegających rozliczeniu. Więcej informacji znajdziesz w sekcji Sygnały dotyczące pytań o stawkę.

Poniższy przykładowy przykład przedstawia cykl życia wczytywania/programu, w którym wywołanie wyświetlenia reklamy może zakończyć się niepowodzeniem.

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, ...);
  }
}