Untuk mendiskusikan dan memberikan masukan tentang produk kami, bergabunglah ke channel Discord Ad Manager resmi di server Komunitas Iklan dan Pengukuran Google.

Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Menyiapkan dengan DAI layanan penuh

Pilih platform: HTML5 Android iOS tvOS Cast Roku

Panduan ini menunjukkan cara mengintegrasikan IMA DAI SDK ke dalam aplikasi pemutar video sederhana. Jika Anda ingin melihat atau mengikuti contoh integrasi yang sudah selesai, download BasicExample dari GitHub.

Ringkasan IMA DAI

Penerapan IMA DAI melibatkan empat komponen SDK utama seperti yang ditunjukkan dalam panduan ini:

StreamDisplayContainer: Objek penampung yang berada di atas elemen pemutaran video dan menampung elemen UI iklan.
AdsLoader: Objek yang meminta streaming dan menangani peristiwa yang dipicu oleh objek respons permintaan streaming. Anda hanya boleh membuat satu instance pemuat iklan, yang dapat digunakan kembali selama masa aktif aplikasi.
StreamRequest: Objek yang menentukan permintaan streaming. Permintaan streaming dapat berupa video on demand atau live stream. Permintaan live stream menentukan kunci aset, sedangkan permintaan VOD menentukan ID CMS dan ID video. Kedua jenis permintaan dapat secara opsional menyertakan kunci API yang diperlukan untuk mengakses streaming yang ditentukan, dan kode jaringan Google Ad Manager untuk IMA SDK guna menangani ID iklan seperti yang ditentukan dalam setelan Google Ad Manager.
StreamManager: Objek yang menangani streaming penyisipan iklan dinamis dan interaksi dengan backend DAI. Pengelola aliran juga menangani ping pelacakan serta meneruskan peristiwa aliran dan iklan ke penayang.

Prasyarat

Android Studio
Aplikasi pemutar video sampel untuk integrasi SDK

Download dan jalankan aplikasi pemutar video sampel

Aplikasi contoh menyediakan pemutar video yang berfungsi untuk memutar video HLS. Gunakan ini sebagai titik awal untuk mengintegrasikan kemampuan DAI IMA DAI SDK.

Download aplikasi pemutar video contoh dan ekstrak.
Mulai Android Studio dan pilih Open an existing Android Studio project, atau jika Android Studio sudah berjalan, pilih File > New > Import Project. Kemudian, pilih SampleVideoPlayer/build.gradle.
Jalankan sinkronisasi Gradle dengan memilih Tools > Android > Sync Project with Gradle Files.
Pastikan aplikasi pemutar mengompilasi dan berjalan di perangkat Android fisik atau Perangkat Virtual Android menggunakan Run > Run 'app'. Wajar jika streaming video memerlukan waktu beberapa saat untuk dimuat sebelum diputar.

Memeriksa contoh pemutar video

Pemutar video sampel belum berisi kode integrasi IMA DAI SDK. Aplikasi contoh terdiri dari dua bagian utama:

samplevideoplayer/SampleVideoPlayer.java: Pemutar HLS berbasis ExoPlayer yang berfungsi sebagai dasar untuk integrasi IMA DAI.
videoplayerapp/MyActivity.java: Aktivitas ini membuat pemutar video dan meneruskan Context dan media3.ui.PlayerView ke pemutar video tersebut.

Menambahkan IMA DAI SDK ke aplikasi pemutar

Anda juga harus menyertakan referensi ke IMA DAI SDK. Di Android Studio, tambahkan kode berikut ke file build.gradle level aplikasi, yang terletak di app/build.gradle. IMA SDK memerlukan pengaktifan desugaring library, yang harus Anda lakukan dengan menetapkan coreLibraryDesugaringEnabled true dan menambahkan 'com.android.tools:desugar_jdk_libs' sebagai dependensi dalam file build.gradle. Untuk mengetahui detailnya, lihat API Java 11+ yang tersedia melalui desugaring dengan spesifikasi nio.

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.11.0"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.21"))
    implementation("androidx.appcompat:appcompat:1.8.0")
    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.40.0")
}build.gradle

Mengintegrasikan IMA DAI SDK

Buat class baru bernama SampleAdsWrapper dalam paket videoplayerapp (di app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) untuk menggabungkan SampleVideoPlayer yang ada dan menambahkan logika yang mengimplementasikan IMA DAI. Untuk melakukannya, Anda harus membuat AdsLoader terlebih dahulu yang digunakan untuk meminta streaming DAI.

Cuplikan ini menyertakan contoh parameter untuk HLS dan DASH, streaming live dan VOD. Untuk menetapkan streaming yang sedang diputar, perbarui variabel 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

Buat metode bantuan createSampleVideoPlayerCallback() untuk menangani pembuatan instance antarmuka SampleVideoPlayerCallback yang memperluas VideoStreamPlayer.VideoStreamPlayerCallback.

Agar dapat berfungsi dengan DAI, pemutar harus meneruskan peristiwa ID3 ke IMA DAI SDK. Metode callback.onUserTextReceived() melakukan hal ini, dalam contoh kode berikut.

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

Tambahkan metode buildStreamRequest() untuk membuat SteamRequest. Metode ini beralih di antara berbagai streaming berdasarkan cara Anda menetapkan variabel CONTENT_TYPE. Streaming default yang digunakan dalam panduan ini adalah streaming HLS VOD contoh 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

Anda juga memerlukan VideoStreamPlayer untuk memutar streaming, jadi tambahkan metode createVideoStreamPlayer(), yang membuat class anonim yang mengimplementasikan 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

Terapkan pemroses yang diperlukan dan tambahkan dukungan untuk penanganan error.

Perhatikan penerapan AdErrorListener, karena penerapan ini memanggil URL pengganti jika iklan gagal diputar. Karena konten dan iklan berada dalam satu streaming, Anda harus siap memanggil streaming penggantian jika streaming DAI mengalami error.

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

Tambahkan kode untuk logging.

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

Ubah MyActivity di videoplayerapp untuk membuat instance dan memanggil SampleAdsWrapper. Selain itu, lakukan panggilan ke ImaSdkFactory.initialize() di sini menggunakan metode helper untuk membuat instance ImaSdkSettings.

Penting: Untuk meningkatkan waktu pemuatan IMA, panggil metode ImaSdkFactory.initialize() sedini mungkin dalam siklus proses aplikasi. Memanggil metode lebih awal akan memaksimalkan waktu bagi IMA untuk memuat resource yang diperlukan sebelum permintaan streaming pertama. Panggilan metode ImaSdkFactory.initialize() menerima instance ImaSdkSettings. Pastikan untuk menggunakan nilai setelan yang sama di sini, dan saat Anda membuat instance AdsLoader. Contoh ini menggunakan metode bantuan getImaSdkSettings() untuk memastikan nilai setelan sama. Untuk mengetahui informasi selengkapnya, lihat Panduan mengoptimalkan waktu pemuatan 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

Tambahkan metode bantuan getImaSdkSettings() untuk membuat instance 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

Ubah file tata letak Aktivitas activity_my.xml untuk menambahkan elemen UI untuk logging.

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

Selamat! Sekarang Anda meminta dan menampilkan iklan video di aplikasi Android. Untuk menyesuaikan penerapan, lihat Bookmark, Snapback, dan dokumentasi API.

Pemecahan masalah

Jika Anda mengalami masalah saat memutar iklan video, coba download BasicExample yang telah selesai. Jika berfungsi dengan baik di BasicExample, kemungkinan ada masalah dengan kode integrasi IMA aplikasi Anda.

Jika Anda masih mengalami masalah, kunjungi forum IMA SDK.