Чтобы обсудить наши продукты и оставить отзыв о них, присоединяйтесь к официальному каналу Ad Manager Discord на сервере Google Advertising and Measurement Community .

Эта страница переведена с помощью Cloud Translation API.

Настройка IMA SDK для DAI

Выберите платформу: HTML5 Android iOS tvOS Cast Roku

SDK IMA упрощают интеграцию мультимедийной рекламы в ваши веб-сайты и приложения. SDK IMA могут запрашивать рекламу с любого рекламного сервера , совместимого с VAST , и управлять воспроизведением рекламы в ваших приложениях. С SDK IMA DAI приложения отправляют запрос на потоковое видео, включающее рекламу и контент — либо видео по запросу, либо прямой эфир. Затем SDK возвращает объединенный видеопоток, так что вам не нужно управлять переключением между рекламой и контентом внутри вашего приложения.

Выберите интересующее вас решение DAI.

Полный спектр услуг DAI

В этом руководстве показано, как интегрировать SDK IMA DAI в простое приложение видеоплеера. Если вы хотите посмотреть или пройтись по готовому примеру интеграции, скачайте BasicExample с GitHub.

Обзор IMA DAI

Реализация IMA DAI включает в себя четыре основных компонента SDK, как показано в этом руководстве:

StreamDisplayContainer : объект-контейнер, который располагается поверх элемента воспроизведения видео и содержит элементы пользовательского интерфейса рекламы.
AdsLoader : Объект, который запрашивает потоки и обрабатывает события, запускаемые объектами запроса и ответа потока. Следует создавать только один экземпляр AdsLoader, который можно использовать повторно на протяжении всего жизненного цикла приложения.
StreamRequest : Объект, определяющий запрос на потоковую передачу. Запросы на потоковую передачу могут быть как для видео по запросу, так и для прямых трансляций. Запросы на прямую трансляцию указывают ключ ресурса, а запросы на видео по запросу — идентификатор CMS и идентификатор видео. Оба типа запросов могут дополнительно включать ключ API, необходимый для доступа к указанным потокам, и сетевой код Google Ad Manager для обработки идентификаторов рекламы в SDK IMA, как указано в настройках Google Ad Manager.
StreamManager : Объект, обрабатывающий потоки динамической вставки рекламы и взаимодействие с бэкэндом DAI. Менеджер потоков также обрабатывает запросы отслеживания и пересылает события потока и рекламы издателю.

Предварительные требования

Android Studio
Пример приложения видеоплеера для интеграции с SDK.

Загрузите и запустите демонстрационное приложение видеоплеера.

В демонстрационном приложении представлен работающий видеоплеер, воспроизводящий видео в формате HLS. Используйте его в качестве отправной точки для интеграции возможностей DAI из SDK IMA DAI.

Скачайте и распакуйте демонстрационный пример приложения видеоплеера .
Запустите Android Studio и выберите «Открыть существующий проект Android Studio» , или, если Android Studio уже запущена, выберите «Файл» > «Новый» > «Импорт проекта» . Затем выберите SampleVideoPlayer/build.gradle .
Для синхронизации Gradle выберите Инструменты > Android > Синхронизировать проект с файлами Gradle .
Убедитесь, что приложение плеера скомпилировано и запущено на физическом устройстве Android или виртуальном устройстве Android, используя команду «Запуск» > «Запустить приложение» . Загрузка видеопотока перед воспроизведением — это нормальное явление.

Изучите пример видеоплеера.

В примере видеоплеера пока отсутствует код интеграции с IMA DAI SDK. Пример приложения состоит из двух основных частей:

samplevideoplayer/SampleVideoPlayer.java : HLS-плеер на основе ExoPlayer , служащий основой для интеграции IMA DAI.
videoplayerapp/MyActivity.java : Эта активность создает видеоплеер и передает ему Context и media3.ui.PlayerView .

Добавьте SDK IMA DAI в приложение проигрывателя.

Также необходимо добавить ссылку на SDK IMA DAI. В Android Studio добавьте следующее в файл build.gradle на уровне приложения, расположенный по адресу app/build.gradle . SDK IMA требует включения десахаризации библиотек, что необходимо сделать, установив параметр coreLibraryDesugaringEnabled true и добавив зависимость 'com.android.tools:desugar_jdk_libs' в файл build.gradle . Подробности см. в разделе «API Java 11+, доступные через десахаризацию с помощью спецификации nio» .

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.9.0"
    coreLibraryDesugaring('com.android.tools:desugar_jdk_libs:2.1.5')
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
    implementation('androidx.appcompat:appcompat:1.7.1')
    implementation("androidx.media3:media3-ui:$media3_version")
    implementation("androidx.media3:media3-exoplayer:$media3_version")
    implementation("androidx.media3:media3-exoplayer-hls:$media3_version")
    implementation("androidx.media3:media3-exoplayer-dash:$media3_version")
    implementation('androidx.mediarouter:mediarouter:1.8.1')
    implementation('com.google.ads.interactivemedia.v3:interactivemedia:3.38.0')
}build.gradle

Интегрируйте SDK IMA DAI.

Создайте новый класс с именем SampleAdsWrapper в пакете videoplayerapp (в app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/ ), чтобы обернуть существующий класс SampleVideoPlayer и добавить логику, реализующую интерфейс IMA DAI. Для этого необходимо сначала создать класс AdsLoader , который будет использоваться для запроса потока DAI.

Этот фрагмент кода содержит примеры параметров для потоков HLS и DASH, прямых трансляций и видео по запросу. Чтобы указать, какой поток воспроизводится, обновите переменную CONTENT_TYPE .

package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.SuppressLint;
import android.content.Context;
import android.view.ViewGroup;
import android.webkit.WebView;
import androidx.annotation.Nullable;
import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.AdsLoader;
import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
import com.google.ads.interactivemedia.v3.api.CuePoint;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer;
import com.google.ads.interactivemedia.v3.api.StreamManager;
import com.google.ads.interactivemedia.v3.api.StreamRequest;
import com.google.ads.interactivemedia.v3.api.StreamRequest.StreamFormat;
import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer.SampleVideoPlayerCallback;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

/** This class adds ad-serving support to Sample HlsVideoPlayer */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class SampleAdsWrapper
    implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

  // Live HLS stream asset key.
  private static final String TEST_HLS_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  // Live DASH stream asset key.
  private static final String TEST_DASH_ASSET_KEY = "PSzZMzAkSXCmlJOWDmRj8Q";

  // VOD HLS content source and video IDs.
  private static final String TEST_HLS_CONTENT_SOURCE_ID = "2548831";
  private static final String TEST_HLS_VIDEO_ID = "tears-of-steel";

  // VOD DASH content source and video IDs.
  private static final String TEST_DASH_CONTENT_SOURCE_ID = "2559737";
  private static final String TEST_DASH_VIDEO_ID = "tos-dash";

  private static final String NETWORK_CODE = "21775744923";

  private static final String PLAYER_TYPE = "DAISamplePlayer";

  private enum ContentType {
    LIVE_HLS,
    LIVE_DASH,
    VOD_HLS,
    VOD_DASH,
  }

  // Set CONTENT_TYPE to the associated enum for the stream type you would like to test.
  private static final ContentType CONTENT_TYPE = ContentType.VOD_HLS;

  /** Log interface, so we can output the log commands to the UI or similar. */
  public interface Logger {
    void log(String logMessage);
  }

  private final ImaSdkFactory sdkFactory;
  private AdsLoader adsLoader;
  private StreamManager streamManager;
  private final List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;

  private final SampleVideoPlayer videoPlayer;
  private final Context context;
  private final ViewGroup adUiContainer;

  private String fallbackUrl;
  private Logger logger;

  /**
   * Creates a new SampleAdsWrapper that implements IMA direct-ad-insertion.
   *
   * @param context the app's context.
   * @param videoPlayer underlying HLS video player.
   * @param adUiContainer ViewGroup in which to display the ad's UI.
   */
  public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) {
    this.videoPlayer = videoPlayer;
    this.context = context;
    this.adUiContainer = adUiContainer;
    sdkFactory = ImaSdkFactory.getInstance();
    playerCallbacks = new ArrayList<>();
    createAdsLoader();
  }

  private void enableWebViewDebugging() {
    WebView.setWebContentsDebuggingEnabled(true);
  }

  private void createAdsLoader() {
    enableWebViewDebugging();
    VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
    StreamDisplayContainer displayContainer =
        ImaSdkFactory.createStreamDisplayContainer(adUiContainer, videoStreamPlayer);
    videoPlayer.setSampleVideoPlayerCallback(createSampleVideoPlayerCallback());
    adsLoader =
        sdkFactory.createAdsLoader(context, MyActivity.getImaSdkSettings(), displayContainer);
  }

  public void requestAndPlayAds() {
    adsLoader.addAdErrorListener(this);
    adsLoader.addAdsLoadedListener(this);
    adsLoader.requestStream(buildStreamRequest());
  }
SampleAdsWrapper.java

Создайте вспомогательный метод createSampleVideoPlayerCallback() для обработки создания экземпляра интерфейса SampleVideoPlayerCallback , который наследует VideoStreamPlayer.VideoStreamPlayerCallback .

Для работы с DAI плеер должен передавать события ID3 в SDK IMA DAI. Это делает метод callback.onUserTextReceived() , как показано в следующем примере кода.

private SampleVideoPlayerCallback createSampleVideoPlayerCallback() {
  return new SampleVideoPlayerCallback() {
    @Override
    public void onUserTextReceived(String userText) {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onUserTextReceived(userText);
      }
    }

    @Override
    public void onSeek(int windowIndex, long positionMs) {
      // See if we would seek past an ad, and if so, jump back to it.
      long newSeekPositionMs = positionMs;
      if (streamManager != null) {
        CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTimeMs(positionMs);
        if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
          newSeekPositionMs = prevCuePoint.getStartTimeMs();
        }
      }
      videoPlayer.seekTo(windowIndex, newSeekPositionMs);
    }

    @Override
    public void onContentComplete() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onContentComplete();
      }
    }

    @Override
    public void onPause() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onPause();
      }
    }

    @Override
    public void onResume() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onResume();
      }
    }

    @Override
    public void onVolumeChanged(int percentage) {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onVolumeChanged(percentage);
      }
    }
  };
}
SampleAdsWrapper.java

Добавьте метод buildStreamRequest() для создания объекта SteamRequest . Этот метод переключается между различными потоками в зависимости от того, как вы задали переменную CONTENT_TYPE . По умолчанию в этом руководстве используется поток VOD HLS от IMA.

@Nullable
private StreamRequest buildStreamRequest() {
  StreamRequest request;
  switch (CONTENT_TYPE) {
    case LIVE_HLS:
      // Live HLS stream request.
      return sdkFactory.createLiveStreamRequest(TEST_HLS_ASSET_KEY, null, NETWORK_CODE);
    case LIVE_DASH:
      // Live DASH stream request.
      return sdkFactory.createLiveStreamRequest(TEST_DASH_ASSET_KEY, null, NETWORK_CODE);
    case VOD_HLS:
      // VOD HLS request.
      request =
          sdkFactory.createVodStreamRequest(
              TEST_HLS_CONTENT_SOURCE_ID, TEST_HLS_VIDEO_ID, null, NETWORK_CODE);
      request.setFormat(StreamFormat.HLS);
      return request;
    case VOD_DASH:
      // VOD DASH request.
      request =
          sdkFactory.createVodStreamRequest(
              TEST_DASH_CONTENT_SOURCE_ID, TEST_DASH_VIDEO_ID, null, NETWORK_CODE);
      request.setFormat(StreamFormat.DASH);
      return request;
  }
  // Content type not selected.
  return null;
}
SampleAdsWrapper.java

Для воспроизведения потока вам также потребуется класс VideoStreamPlayer , поэтому добавьте метод createVideoStreamPlayer() , который создаст анонимный класс, реализующий интерфейс VideoStreamPlayer .

private VideoStreamPlayer createVideoStreamPlayer() {
  return new VideoStreamPlayer() {
    @Override
    public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
      videoPlayer.setStreamUrl(url);
      videoPlayer.play();
    }

    @Override
    public void pause() {
      // Pause player.
      videoPlayer.pause();
    }

    @Override
    public void resume() {
      // Resume player.
      videoPlayer.play();
    }

    @Override
    public int getVolume() {
      // Make the video player play at the current device volume.
      return 100;
    }

    @Override
    public void addCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
      playerCallbacks.add(videoStreamPlayerCallback);
    }

    @Override
    public void removeCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
      playerCallbacks.remove(videoStreamPlayerCallback);
    }

    @Override
    public void onAdBreakStarted() {
      // Disable player controls.
      videoPlayer.enableControls(false);
      log("Ad Break Started\n");
    }

    @Override
    public void onAdBreakEnded() {
      // Re-enable player controls.
      if (videoPlayer != null) {
        videoPlayer.enableControls(true);
      }
      log("Ad Break Ended\n");
    }

    @Override
    public void onAdPeriodStarted() {
      log("Ad Period Started\n");
    }

    @Override
    public void onAdPeriodEnded() {
      log("Ad Period Ended\n");
    }

    @Override
    public void seek(long timeMs) {
      // An ad was skipped. Skip to the content time.
      videoPlayer.seekTo(timeMs);
      log("seek");
    }

    @Override
    public VideoProgressUpdate getContentProgress() {
      return new VideoProgressUpdate(
          videoPlayer.getCurrentPositionMs(), videoPlayer.getDuration());
    }
  };
}
SampleAdsWrapper.java

Реализуйте необходимые обработчики событий и добавьте поддержку обработки ошибок.

Обратите внимание на реализацию AdErrorListener , поскольку она вызывает резервный URL-адрес, если воспроизведение рекламы не удается. Поскольку контент и реклама находятся в одном потоке, вы должны быть готовы вызвать резервный поток, если в потоке DAI возникнет ошибка.

/** AdErrorListener implementation */
@Override
public void onAdError(AdErrorEvent event) {
  log(String.format("Error: %s\n", event.getError().getMessage()));
  // play fallback URL.
  log("Playing fallback Url\n");
  videoPlayer.setStreamUrl(fallbackUrl);
  videoPlayer.enableControls(true);
  videoPlayer.play();
}

/** AdEventListener implementation */
@Override
public void onAdEvent(AdEvent event) {
  switch (event.getType()) {
    case AD_PROGRESS:
      // Do nothing or else log will be filled by these messages.
      break;
    default:
      log(String.format("Event: %s\n", event.getType()));
      break;
  }
}

/** AdsLoadedListener implementation */
@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  streamManager = event.getStreamManager();
  streamManager.addAdErrorListener(this);
  streamManager.addAdEventListener(this);
  streamManager.init();
}

/** Sets fallback URL in case ads stream fails. */
void setFallbackUrl(String url) {
  fallbackUrl = url;
}
SampleAdsWrapper.java

Добавьте код для логирования.

/** Sets logger for displaying events to screen. Optional. */
void setLogger(Logger logger) {
  this.logger = logger;
}

private void log(String message) {
  if (logger != null) {
    logger.log(message);
  }
}SampleAdsWrapper.java

Измените MyActivity в videoplayerapp , чтобы он создавал экземпляр SampleAdsWrapper и вызывал его. Также, используя вспомогательный метод, вызовите метод ImaSdkFactory.initialize() для создания экземпляра класса ImaSdkSettings .

Важно: Чтобы сократить время загрузки IMA, вызывайте метод ImaSdkFactory.initialize() как можно раньше в жизненном цикле приложения. Ранний вызов метода максимизирует время загрузки необходимых ресурсов IMA до первого запроса потока. Метод ImaSdkFactory.initialize() принимает экземпляр ImaSdkSettings . Убедитесь, что вы используете те же значения настроек здесь и при создании экземпляра AdsLoader . В этом примере используется вспомогательный метод getImaSdkSettings() для обеспечения совпадения значений настроек. Для получения дополнительной информации см. руководство по оптимизации времени загрузки IMA .

package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.SuppressLint;
import android.app.Activity;
import android.content.res.Configuration;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.ImageButton;
import android.widget.ScrollView;
import android.widget.TextView;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;

/** Main Activity that plays media using {@link SampleVideoPlayer}. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String DEFAULT_STREAM_URL =
      "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
  private static final String APP_LOG_TAG = "ImaDaiExample";
  private static final String PLAYER_TYPE = "DAISamplePlayer";
  private static ImaSdkSettings imaSdkSettings;

  protected SampleVideoPlayer sampleVideoPlayer;
  protected ImageButton playButton;

  private boolean contentHasStarted = false;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_my);

    // Initialize the IMA SDK as early as possible when the app starts. If your app already
    // overrides Application.onCreate(), call this method inside the onCreate() method.
    // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
    ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());

    View rootView = findViewById(R.id.videoLayout);
    sampleVideoPlayer =
        new SampleVideoPlayer(rootView.getContext(), rootView.findViewById(R.id.playerView));
    sampleVideoPlayer.enableControls(false);
    playButton = rootView.findViewById(R.id.playButton);
    final SampleAdsWrapper sampleAdsWrapper =
        new SampleAdsWrapper(this, sampleVideoPlayer, rootView.findViewById(R.id.adUiContainer));
    sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);

    final ScrollView scrollView = findViewById(R.id.logScroll);
    final TextView textView = findViewById(R.id.logText);

    sampleAdsWrapper.setLogger(
        logMessage -> {
          Log.i(APP_LOG_TAG, logMessage);
          if (textView != null) {
            textView.append(logMessage);
          }
          if (scrollView != null) {
            scrollView.post(() -> scrollView.fullScroll(View.FOCUS_DOWN));
          }
        });

    // Set up play button listener to play video then hide play button.
    playButton.setOnClickListener(
        view -> {
          if (contentHasStarted) {
            sampleVideoPlayer.play();
          } else {
            contentHasStarted = true;
            sampleVideoPlayer.enableControls(true);
            sampleAdsWrapper.requestAndPlayAds();
          }
          playButton.setVisibility(View.GONE);
        });
    orientVideoDescription(getResources().getConfiguration().orientation);
  }
MyActivity.java

Добавьте вспомогательный метод getImaSdkSettings() для создания экземпляра ImaSdkSettings .

public static ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    imaSdkSettings.setPlayerType(PLAYER_TYPE);
    // Set any additional IMA SDK settings here.
  }
  return imaSdkSettings;
}MyActivity.java

Измените файл разметки activity_my.xml , добавив элементы пользовательского интерфейса для ведения журнала.

<!-- UI element for viewing SDK event log -->
<ScrollView
    android:id="@+id/logScroll"
    android:layout_width="match_parent"
    android:layout_height="0dp"
    android:layout_weight="0.5"
    android:padding="5dp"
    android:background="#DDDDDD">

    <TextView
        android:id="@+id/logText"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">
    </TextView>
</ScrollView>activity_my.xml

Поздравляем! Теперь вы запрашиваете и отображаете видеорекламу в своем Android-приложении. Для более точной настройки см. разделы «Закладки» , «Snapback» и документацию по API .

Поиск неисправностей

Если у вас возникли проблемы с воспроизведением видеорекламы, попробуйте загрузить готовый BasicExample . Если в BasicExample все работает корректно, то, скорее всего, проблема в коде интеграции IMA вашего приложения.

Если проблемы сохраняются, посетите форум IMA SDK .