Exoplayer IMA 확장 프로그램 시작하기

IMA SDK를 사용하면 웹사이트와 앱에 멀티미디어 광고를 쉽게 통합할 수 있습니다. IMA SDK는 VAST 호환 광고 서버에서 광고를 요청하고 앱에서 광고 재생을 관리할 수 있습니다. IMA 클라이언트 측 SDK를 사용하면 콘텐츠 동영상 재생을 제어할 수 있으며 SDK가 광고 재생을 처리합니다. 광고는 앱의 콘텐츠 동영상 플레이어 위에 배치된 별도의 동영상 플레이어에서 재생됩니다.

이 가이드에서는 ExoPlayer IMA 확장 프로그램을 사용하여 빈 Android 스튜디오 프로젝트에 IMA SDK를 통합하는 방법을 보여줍니다. 완성된 샘플 통합을 보거나 따라 하려면 GitHub에서 BasicExample을 다운로드하세요.

IMA 클라이언트 측 개요

IMA 클라이언트 측 구현에는 이 가이드에 설명된 네 가지 주요 SDK 구성요소가 필요합니다.

  • AdDisplayContainer: IMA가 광고 UI 요소를 렌더링하고 Active View 및 Open Measurement를 비롯한 조회가능성을 측정하는 위치를 지정하는 컨테이너 객체입니다.
  • AdsLoader: 광고를 요청하고 광고 요청 응답의 이벤트를 처리하는 객체입니다. 애플리케이션 수명 동안 재사용할 수 있는 광고 로더를 하나만 인스턴스화해야 합니다.
  • AdsRequest: 광고 요청을 정의하는 객체입니다. 광고 요청은 VAST 광고 태그의 URL과 광고 크기와 같은 추가 매개변수를 지정합니다.
  • AdsManager: 광고 요청에 대한 응답을 포함하고, 광고 재생을 제어하며, SDK에서 발생한 광고 이벤트를 수신하는 객체입니다.

기본 요건

시작하기 전에 Android 스튜디오 3.0 이상이 필요합니다.

1. 새 Android 스튜디오 프로젝트 만들기

Android 스튜디오 프로젝트를 만들려면 다음 단계를 완료하세요.

  1. Android 스튜디오를 시작합니다.
  2. Start a new Android Studio project를 선택합니다.
  3. Choose your project 페이지에서 Empty Activity 템플릿을 선택합니다.
  4. 다음을 클릭합니다.
  5. 프로젝트 구성 페이지에서 프로젝트 이름을 지정하고 언어로 Java를 선택합니다.
  6. 마침을 클릭합니다.

2. 프로젝트에 ExoPlayer IMA 확장 프로그램 추가

먼저 애플리케이션 수준 build.gradle 파일의 종속 항목 섹션에 확장 프로그램의 가져오기를 추가합니다. 또한 Java 버전 호환성 정보를 지정하는 새 compileOptions를 추가합니다. 

apply plugin: 'com.android.application'

android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdk 36

    // Java 17 required by Gradle 8+
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    defaultConfig {
        applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
        minSdkVersion 21
        targetSdkVersion 36
        multiDexEnabled true
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.8.0"
    implementation "androidx.media3:media3-ui:$media3_version"
    implementation "androidx.media3:media3-exoplayer:$media3_version"

    // The library adds the IMA ExoPlayer integration for ads.
    implementation "androidx.media3:media3-exoplayer-ima:$media3_version"

    implementation 'androidx.multidex:multidex:2.0.1'
}

build.gradle

3. 광고 UI 컨테이너 만들기

androidx.media3.ui.PlayerView를 만들어 ExoPlayer PlayerView로 사용할 뷰를 만듭니다. 또한 androidx.constraintlayout.widget.ConstraintLayout을 LinearLayout로 변경합니다. 

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MyActivity"
    tools:ignore="MergeRootFrame">

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

    <!-- UI element for viewing SDK event log -->
    <TextView
        android:id="@+id/logText"
        android:gravity="bottom"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:maxLines="100"
        android:scrollbars="vertical"
        android:textSize="@dimen/font_size">
    </TextView>

</LinearLayout>

activity_my.xml

4. ExoPlayer IMA 확장 프로그램 가져오기

ExoPlayer 확장 프로그램의 가져오기 문을 추가합니다.

import static android.os.Build.VERSION.SDK_INT;

import android.annotation.SuppressLint;
import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import android.text.method.ScrollingMovementMethod;
import android.util.Log;
import android.widget.TextView;
import androidx.media3.common.MediaItem;
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;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;

MyActivity.java

그런 다음 PlayerView, ExoPlayer, ImaAdsLoader, ImaSdkSettings의 비공개 변수를 추가하여 Activity를 확장하도록 MainActivity 클래스를 업데이트합니다. 

/** Main Activity. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String SAMPLE_VIDEO_URL =
      "https://storage.googleapis.com/gvabox/media/samples/stock.mp4";
  private static final String SAMPLE_VAST_TAG_URL =
      "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&correlator=";
  private static final String LOG_TAG = "ImaExoPlayerExample";

  private PlayerView playerView;
  private TextView logText;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;
  private ImaSdkSettings imaSdkSettings;

MyActivity.java

5. adsLoader 인스턴스 만들기

onCreate 메서드를 덮어쓰고 필수 변수 할당을 추가하여 광고 태그 URL이 포함된 새 adsLoader 객체를 만듭니다. 

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

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

  playerView = findViewById(R.id.player_view);

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

MyActivity.java

디버깅을 위해 IMA 이벤트를 로깅하는 AdEventListener 객체를 반환하는 buildAdEventListener() 메서드를 만듭니다. ExoPlayer IMA 확장 프로그램은 이미 IMA 이벤트를 처리하므로 여기서 추가로 필요한 것은 없습니다. 

public AdEvent.AdEventListener buildAdEventListener() {
  logText = findViewById(R.id.logText);
  logText.setMovementMethod(new ScrollingMovementMethod());

  return event -> {
    AdEvent.AdEventType eventType = event.getType();
    if (eventType == AdEvent.AdEventType.AD_PROGRESS) {
      return;
    }
    String log = "IMA event: " + eventType;
    if (logText != null) {
      logText.append(log + "\n");
    }
    Log.i(LOG_TAG, log);
  };
}

MyActivity.java

ImaSdkSettings 객체를 반환하여 IMA SDK 설정을 설정하는 getImaSdkSettings() 도우미 메서드를 만듭니다. 

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

6. 플레이어 초기화 및 해제

플레이어를 해제하고 초기화하는 메서드 추가 initializePlayer() 메서드에서 ExoPlayer를 만듭니다. 그런 다음 AdsMediaSource를 만들어 플레이어에 설정합니다.

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(SAMPLE_VIDEO_URL);
  Uri adTagUri = Uri.parse(SAMPLE_VAST_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);
}

MyActivity.java

7. 플레이어 이벤트 처리

마지막으로 플레이어의 수명 주기 이벤트에 대한 콜백을 만듭니다.

  • onStart
  • onResume
  • onStop
  • onPause
  • onDestroy
@Override
public void onStart() {
  super.onStart();
  if (SDK_INT > 23) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

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

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

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

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

  super.onDestroy();
}

MyActivity.java

이제 IMA SDK를 사용하여 광고를 요청하고 표시할 수 있습니다. 고급 기능에 대해 자세히 알아보려면 다른 가이드나 GitHub의 샘플을 살펴보세요.