Halaman ini diterjemahkan oleh Cloud Translation API.

Mulai menggunakan ekstensi IMA Exoplayer

IMA SDK memudahkan pengintegrasian iklan multimedia ke dalam situs dan aplikasi Anda. IMA SDK dapat meminta iklan dari server iklan apa pun yang sesuai dengan VAST dan mengelola pemutaran iklan di aplikasi Anda. Dengan SDK sisi klien IMA, Anda mempertahankan kontrol atas pemutaran video konten, sedangkan SDK menangani pemutaran iklan. Iklan diputar di pemutar video terpisah yang diposisikan di atas pemutar video konten aplikasi.

Panduan ini menunjukkan cara mengintegrasikan IMA SDK ke dalam project Android Studio kosong menggunakan ekstensi IMA ExoPlayer. Jika Anda ingin melihat atau mengikuti contoh integrasi yang telah selesai, download BasicExample dari GitHub.

Ringkasan sisi klien IMA

Mengimplementasikan IMA sisi klien melibatkan empat komponen SDK utama, yang ditunjukkan dalam panduan ini:

AdDisplayContainer: Objek penampung tempat iklan dirender.
AdsLoader: Objek yang meminta iklan dan menangani peristiwa dari respons permintaan iklan. Anda hanya boleh membuat instance satu loader iklan, yang dapat digunakan kembali selama masa pakai aplikasi.
AdsRequest: Objek yang menentukan permintaan iklan. Permintaan iklan menentukan URL untuk tag iklan VAST, serta parameter tambahan, seperti dimensi iklan.
AdsManager: Objek yang berisi respons terhadap permintaan iklan, mengontrol pemutaran iklan, dan memproses peristiwa iklan yang diaktifkan oleh SDK.

Catatan: Karena ekstensi IMA ExoPlayer menggabungkan IMA SDK dalam panduan ini, AdsRequest dan AdsManager sedang digunakan, tetapi tidak dipanggil secara eksplisit.

Prasyarat

Sebelum memulai, Anda memerlukan Android Studio 3.0 atau yang lebih tinggi.

1. Membuat project Android Studio baru

Untuk membuat project Android Studio, selesaikan langkah-langkah berikut:

Mulai Android Studio.
Pilih Start a new Android Studio project.
Di halaman Choose your project, pilih template Empty Activity.
Klik Next.
Di halaman Configure your project, beri nama project Anda dan pilih Java untuk bahasa.
Catatan: IMA SDK kompatibel dengan Kotlin. Namun, contoh yang tercakup dalam panduan ini menggunakan Java.
Klik Selesai.

2. Menambahkan ekstensi IMA ExoPlayer ke project Anda

Pertama, pada file build.gradle tingkat aplikasi, tambahkan impor untuk ekstensi ke bagian dependensi. Karena ukuran ekstensi IMA ExoPlayer, implementasikan dan aktifkan multidex di sini. Hal ini diperlukan untuk aplikasi dengan minSdkVersion yang ditetapkan ke 20 atau yang lebih rendah. Selain itu, tambahkan compileOptions baru untuk menentukan informasi kompatibilitas versi Java.

app/build.gradle

android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdkVersion 34

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
  }

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
      minSdkVersion 21
      targetSdkVersion 34
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.2.1'
    implementation 'androidx.media3:media3-exoplayer:1.2.1'
    implementation 'androidx.media3:media3-exoplayer-ima:1.2.1'

    ...
}

Tambahkan izin pengguna yang diperlukan oleh IMA SDK untuk meminta iklan.

app/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.project name">

    <!-- Required permissions for the IMA SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

Menambahkan deklarasi intent

Jika aplikasi Anda menargetkan Android 11 (level API 30) atau yang lebih baru, versi IMA SDK saat ini dan yang terbaru memerlukan deklarasi intent eksplisit untuk membuka link web. Tambahkan cuplikan berikut ke file manifes aplikasi Anda untuk mengaktifkan klik-tayang iklan (pengguna mengklik tombol Pelajari lebih lanjut).

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.example.project name">

      ...

    </application>

    <queries>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="https" />
      </intent>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="http" />
      </intent>
    </queries>
  </manifest>

3. Membuat penampung UI iklan

Membuat tampilan untuk digunakan sebagai ExoPlayer PlayerView dengan membuat objek StyledPlayerView dengan ID yang sesuai. Selain itu, ubah juga androidx.constraintlayout.widget.ConstraintLayout menjadi LinearLayout.

app/src/main/res/layout/activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

</LinearLayout>

4. Menambahkan URL konten dan URL tag iklan untuk permintaan iklan

Tambahkan entri ke strings.xml untuk menyimpan URL konten dan URL tag iklan VAST Anda.

app/src/main/res/values/strings.xml

<resources>
    <string name="app_name">Your_Project_Name</string>
    <string name="content_url"><![CDATA[https://storage.googleapis.com/gvabox/media/samples/stock.mp4]]></string>
    <string name="ad_tag_url"><![CDATA[https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=]]></string>

</resources>

5. Mengimpor ekstensi IMA ExoPlayer

Menambahkan pernyataan impor untuk ekstensi ExoPlayer. Kemudian, update class MainActivity untuk memperluas Activity dengan menambahkan variabel pribadi untuk PlayerView, SimpleExoPlayer, dan ImaAdsLoader.

app/src/main/java/com/example/project name/MainActivity.java


import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.media3.common.MediaItem;
import androidx.media3.common.util.Util;
import androidx.media3.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.exoplayer.ExoPlayer;
import androidx.media3.exoplayer.ima.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

}

6. Membuat instance `adsLoader`

Timpa metode onCreate dan tambahkan penetapan variabel yang diperlukan untuk membuat objek adsLoader baru dengan URL tag iklan.

app/src/main/java/com/example/project name/MainActivity.java


...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    MultiDex.install(this);

    playerView = findViewById(R.id.player_view);

    // Create an AdsLoader.
      adsLoader =
        new ImaAdsLoader.Builder(/* context= */ this)
            .setAdEventListener(buildAdEventListener())
            .build();
  }

  public AdEvent.AdEventListener buildAdEventListener() {

    AdEvent.AdEventListener imaAdEventListener = event -> {
      AdEvent.AdEventType eventType = event.getType();
      // Log IMA events for debugging.
      // The ExoPlayer IMA extension already handles IMA events and does not need anything
      // additional here to function.
    };

    return imaAdEventListener;
  }

}

7. Melakukan inisialisasi dan merilis pemutar

Tambahkan metode untuk melakukan inisialisasi dan melepaskan pemutar. Pada metode inisialisasi, buat SimpleExoPlayer. Kemudian, buat AdsMediaSource dan tetapkan ke pemutar.

app/src/main/java/com/example/project name/MainActivity.java

public class MainActivity extends Activity {

  ...

  private void releasePlayer() {
    adsLoader.setPlayer(null);
    playerView.setPlayer(null);
    player.release();
    player = null;
  }

  private void initializePlayer() {
    // Set up the factory for media sources, passing the ads loader and ad view providers.
    DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

    MediaSource.Factory mediaSourceFactory =
        new DefaultMediaSourceFactory(dataSourceFactory)
            .setLocalAdInsertionComponents(unusedAdTagUri -> adsLoader, playerView);

    // Create an ExoPlayer and set it as the player for content and ads.
    player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
    playerView.setPlayer(player);
    adsLoader.setPlayer(player);

    // Create the MediaItem to play, specifying the content URI and ad tag URI.
    Uri contentUri = Uri.parse(getString(R.string.content_url));
    Uri adTagUri = Uri.parse(getString(R.string.ad_tag_url));
    MediaItem mediaItem =
        new MediaItem.Builder()
            .setUri(contentUri)
            .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
            .build();

    // Prepare the content and ad to be played with the SimpleExoPlayer.
    player.setMediaItem(mediaItem);
    player.prepare();

    // Set PlayWhenReady. If true, content and ads will autoplay.
    player.setPlayWhenReady(false);
  }
}

8. Menangani peristiwa pemain

Terakhir, buat callback untuk peristiwa siklus proses pemain:

onStart
onResume
onStop
onPause
onDestroy

Catatan: Kode contoh menggunakan onStart/onStop untuk Android SDK versi 24 dan yang lebih baru, serta onResume/onPause untuk versi sebelum 24.

app/src/main/java/com/example/project name/MainActivity.java

public class MainActivity extends Activity {

  private PlayerView playerView;
  private SimpleExoPlayer player;
  private ImaAdsLoader adsLoader;

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

      playerView = findViewById(R.id.player_view);

      // Create an AdsLoader.
      adsLoader =
        new ImaAdsLoader.Builder(/* context= */ this)
            .setAdEventListener(buildAdEventListener())
            .build();
  }

  @Override
  public void onStart() {
    super.onStart();
    //
    if (Util.SDK_INT > 23) {
      initializePlayer();
      if (playerView != null) {
        playerView.onResume();
      }
    }
  }

  @Override
  public void onResume() {
    super.onResume();
    if (Util.SDK_INT <= 23 || player == null) {
      initializePlayer();
      if (playerView != null) {
        playerView.onResume();
      }
    }
  }

  @Override
  public void onPause() {
    super.onPause();
    if (Util.SDK_INT <= 23) {
      if (playerView != null) {
        playerView.onPause();
      }
      releasePlayer();
    }
  }

  @Override
  public void onStop() {
    super.onStop();
    if (Util.SDK_INT > 23) {
      if (playerView != null) {
        playerView.onPause();
      }
      releasePlayer();
    }
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    adsLoader.release();
  }

  ...

}

Selesai. Anda kini meminta dan menampilkan iklan dengan IMA SDK. Untuk mempelajari fitur-fitur tambahan SDK, lihat panduan lainnya atau contoh di GitHub.

Mulai menggunakan ekstensi IMA Exoplayer

Ringkasan sisi klien IMA

Prasyarat

1. Membuat project Android Studio baru

2. Menambahkan ekstensi IMA ExoPlayer ke project Anda

Menambahkan deklarasi intent

3. Membuat penampung UI iklan

4. Menambahkan URL konten dan URL tag iklan untuk permintaan iklan

5. Mengimpor ekstensi IMA ExoPlayer

6. Membuat instance adsLoader

7. Melakukan inisialisasi dan merilis pemutar

8. Menangani peristiwa pemain

6. Membuat instance `adsLoader`