Thiết lập SDK IMA cho DAI

Chọn nền tảng: HTML5 Android iOS tvOS Cast Roku

SDK IMA giúp bạn dễ dàng tích hợp quảng cáo đa phương tiện vào trang web và ứng dụng của mình. SDK IMA có thể yêu cầu quảng cáo từ bất kỳ máy chủ quảng cáo tuân thủ VAST nào và quản lý việc phát quảng cáo trong ứng dụng của bạn. Với SDK DAI của IMA, các ứng dụng sẽ đưa ra yêu cầu về luồng cho quảng cáo và video nội dung – có thể là nội dung VOD hoặc nội dung trực tiếp. Sau đó, SDK sẽ trả về một luồng video kết hợp, nhờ đó bạn không phải quản lý việc chuyển đổi giữa quảng cáo và video nội dung trong ứng dụng của mình.

Chọn giải pháp DAI mà bạn quan tâm

DAI trọn gói

Hướng dẫn này minh hoạ cách tích hợp IMA DAI SDK vào một ứng dụng trình phát video đơn giản. Nếu muốn xem hoặc làm theo một mẫu tích hợp hoàn chỉnh, hãy tải BasicExample xuống từ GitHub.

Tổng quan về DAI của IMA

Việc triển khai IMA DAI bao gồm 4 thành phần SDK chính như minh hoạ trong hướng dẫn này:

  • StreamDisplayContainer: Một đối tượng vùng chứa nằm phía trên phần tử phát video và chứa các phần tử giao diện người dùng quảng cáo.
  • AdsLoader: Một đối tượng yêu cầu luồng và xử lý các sự kiện do đối tượng phản hồi yêu cầu luồng kích hoạt. Bạn chỉ nên khởi tạo một trình tải quảng cáo và có thể dùng lại trình tải này trong suốt thời gian hoạt động của ứng dụng.
  • StreamRequest: Một đối tượng xác định yêu cầu phát trực tuyến. Yêu cầu phát trực tuyến có thể là yêu cầu phát video theo yêu cầu hoặc phát trực tiếp. Các yêu cầu phát trực tiếp chỉ định một khoá thành phần, trong khi các yêu cầu VOD chỉ định một mã CMS và mã video. Cả hai loại yêu cầu đều có thể bao gồm một khoá API (không bắt buộc) cần thiết để truy cập vào các luồng truyền phát được chỉ định và mã mạng Google Ad Manager để SDK IMA xử lý mã nhận dạng quảng cáo như được chỉ định trong phần cài đặt Google Ad Manager.
  • StreamManager: Một đối tượng xử lý các luồng chèn quảng cáo động và các lượt tương tác với phần phụ trợ DAI. Trình quản lý luồng phát cũng xử lý các ping theo dõi và chuyển tiếp các sự kiện luồng phát và quảng cáo đến nhà xuất bản.

Điều kiện tiên quyết

  • Android Studio
  • Ứng dụng trình phát video mẫu để tích hợp SDK

Tải xuống và chạy ứng dụng trình phát video mẫu

Ứng dụng mẫu cung cấp một trình phát video hoạt động và phát video HLS. Hãy sử dụng thông tin này làm điểm bắt đầu để tích hợp các chức năng DAI của SDK IMA DAI.

  1. Tải ứng dụng trình phát video mẫu xuống và giải nén.

  2. Khởi động Android Studio rồi chọn Mở một dự án Android Studio hiện có, hoặc nếu Android Studio đã chạy, hãy chọn Tệp > Mới > Nhập dự án. Sau đó, hãy chọn SampleVideoPlayer/build.gradle.

  3. Chạy một quy trình đồng bộ hoá Gradle bằng cách chọn Tools > Android > Sync Project with Gradle Files (Công cụ > Android > Đồng bộ hoá dự án với các tệp Gradle).

  4. Đảm bảo rằng ứng dụng trình phát biên dịch và chạy trên một thiết bị Android thực hoặc một Thiết bị Android ảo bằng cách sử dụng Run > Run 'app' (Chạy > Chạy "ứng dụng"). Việc luồng video mất vài phút để tải trước khi phát là điều bình thường.

Khám phá trình phát video mẫu

Trình phát video mẫu chưa có mã tích hợp SDK DAI của IMA. Ứng dụng mẫu này gồm 2 phần chính:

  1. samplevideoplayer/SampleVideoPlayer.java: Trình phát HLS dựa trên ExoPlayer đóng vai trò là cơ sở cho việc tích hợp DAI của IMA.

  2. videoplayerapp/MyActivity.java: Hoạt động này tạo trình phát video và truyền cho trình phát đó một Context và media3.ui.PlayerView.

Thêm IMA DAI SDK vào ứng dụng trình phát

Bạn cũng phải thêm một thông tin tham chiếu đến IMA DAI SDK. Trong Android Studio, hãy thêm nội dung sau vào tệp build.gradle ở cấp ứng dụng, nằm tại app/build.gradle. SDK IMA yêu cầu bật tính năng khử đường dẫn thư viện. Bạn phải thực hiện việc này bằng cách đặt coreLibraryDesugaringEnabled true và thêm coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5' làm phần phụ thuộc trong tệp build.gradle. Để biết thêm thông tin, hãy xem phần Các API Java 11 trở lên hiện có thông qua quy trình đơn giản hoá bằng thông số kỹ thuật nio.

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.8.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

Tích hợp IMA DAI SDK

  1. Tạo một lớp mới có tên là SampleAdsWrapper trong gói videoplayerapp (trong app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) để bao bọc SampleVideoPlayer hiện có và thêm logic triển khai IMA DAI. Để làm việc này, trước tiên, bạn phải tạo một AdsLoader dùng để yêu cầu luồng DAI.

    Đoạn mã này bao gồm các tham số mẫu cho HLS và DASH, luồng phát trực tiếp và luồng VOD. Để đặt luồng đang phát, hãy cập nhật biến 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

  2. Tạo một phương thức trợ giúp createSampleVideoPlayerCallback() để xử lý việc tạo một thực thể giao diện SampleVideoPlayerCallback mở rộng VideoStreamPlayer.VideoStreamPlayerCallback.

    Để hoạt động với DAI, trình phát phải truyền các sự kiện ID3 đến SDK IMA DAI. Phương thức callback.onUserTextReceived() thực hiện việc này trong đoạn mã mẫu sau.

    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

  3. Thêm phương thức buildStreamRequest() để tạo SteamRequest. Phương thức này chuyển đổi giữa các luồng khác nhau dựa trên cách bạn đặt biến CONTENT_TYPE. Luồng mặc định được dùng trong hướng dẫn này là luồng HLS VOD mẫu của 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

  4. Bạn cũng cần một VideoStreamPlayer để phát luồng, vì vậy, hãy thêm phương thức createVideoStreamPlayer(). Phương thức này sẽ tạo một lớp ẩn danh triển khai 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

  5. Triển khai các trình nghe bắt buộc và thêm tính năng hỗ trợ xử lý lỗi.

    Lưu ý việc triển khai AdErrorListener, vì phương thức này sẽ gọi một URL dự phòng nếu quảng cáo không phát được. Vì nội dung và quảng cáo nằm trong cùng một luồng, nên bạn phải sẵn sàng gọi một luồng dự phòng nếu luồng DAI gặp lỗi.

    /** 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

  6. Thêm mã để ghi nhật ký.

    /** 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

  7. Sửa đổi MyActivity trong videoplayerapp để khởi tạo và gọi SampleAdsWrapper. Ngoài ra, hãy gọi ImaSdkFactory.initialize() tại đây bằng phương thức trợ giúp để tạo một thực thể ImaSdkSettings.

    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

  8. Thêm phương thức trợ giúp getImaSdkSettings() để tạo một thực thể 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

  9. Sửa đổi tệp bố cục activity_my.xml của Hoạt động để thêm các phần tử trên giao diện người dùng để ghi nhật ký.

    <!-- 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

Xin chúc mừng! Giờ đây, bạn đang yêu cầu và hiển thị quảng cáo dạng video trong ứng dụng Android của mình. Để tinh chỉnh việc triển khai, hãy xem Bookmarks (Dấu trang), Snapback (Quay lại nhanh) và tài liệu API.

Khắc phục sự cố

Nếu bạn gặp vấn đề khi phát một quảng cáo dạng video, hãy thử tải BasicExample đã hoàn tất xuống. Nếu hoạt động đúng cách trong BasicExample, thì có thể mã tích hợp IMA của ứng dụng của bạn có vấn đề.

Nếu bạn vẫn gặp vấn đề, hãy truy cập vào diễn đàn IMA SDK.