תחילת השימוש בתוסף IMA של Exoplayer

IMA SDK מאפשר לכם לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות שלכם. IMA SDK יכול לשלוח בקשה להצגת מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות שלך. ערכות SDK בצד הלקוח של IMA מאפשרות לך לשלוט בהפעלה של תוכן וידאו, בעוד מערכת ה-SDK מטפלת בהפעלת המודעות. המודעות מופעלות בנגן וידאו נפרד שממוקם מעל נגן הווידאו של תוכן האפליקציה.

המדריך הזה מדגים איך לשלב את IMA SDK בפרויקט ריק ב-Android Studio באמצעות תוסף IMA של ExoPlayer. אם אתם רוצים לראות שילוב לדוגמה שהושלם או לעקוב אחריו, תוכלו להוריד את BasicExample מ-GitHub.

הערה: למידע על שילוב עם פלטפורמות אחרות או על השימוש ב-IMA DAI SDK, אפשר לעיין במאמר ערכות SDK של מודעות מדיה אינטראקטיביות.

סקירה כללית של IMA בצד הלקוח

ההטמעה של IMA בצד הלקוח כוללת ארבעה רכיבי SDK עיקריים, שמפורטים במדריך הזה:

• AdDisplayContainer: אובייקט מאגר תגים שבו מודעות מעובדות.
• AdsLoader: אובייקט שמבקש מודעות ומטפל באירועים מתגובות לבקשות למודעות. יש להפעיל רק טוען מודעות אחד, שניתן לעשות בו שימוש חוזר במהלך חיי האפליקציה.
• AdsRequest: אובייקט שמגדיר בקשה להצגת מודעות. בקשות להצגת מודעות מציינות את כתובת ה-URL של תג המודעה VAST, וגם פרמטרים נוספים, כמו מאפייני המודעה.
• AdsManager: אובייקט שמכיל את התגובה לבקשה להצגת מודעה, שולט בהפעלת המודעות ומאזין לאירועי מודעות שהופעלו על ידי ה-SDK.

הערה: מאחר שתוסף IMA של ExoPlayer אוחז את IMA SDK במדריך הזה, נעשה שימוש גם ב-AdsRequest וגם ב-AdsManager, אבל לא קוראים לזה באופן מפורש.

דרישות מוקדמות

לפני שמתחילים, צריך Android Studio 3.0 ואילך.

1. יצירת פרויקט חדש ב-Android Studio

כדי ליצור פרויקט Android Studio, מבצעים את השלבים הבאים:

1. מפעילים את Android Studio.
2. בוחרים באפשרות התחלת פרויקט חדש ב-Android Studio.
3. בדף Choose your project, בוחרים את התבנית Empty Activity.
4. לוחצים על הבא.
5. בדף Configure your project, נותנים שם לפרויקט ובוחרים ב-Java לשפה.
   הערה: IMA SDK תואם ל-Kotlin. עם זאת, הדוגמה המתוארת במדריך הזה משתמשת ב-Java.
6. לוחצים על סיום.

2. הוספת תוסף IMA של ExoPlayer לפרויקט

קודם כול, בקובץ build.gradle ברמת האפליקציה, מוסיפים ייבוא של התוסף לקטע של יחסי התלות. בגלל הגודל של תוסף IMA של ExoPlayer, כדאי להטמיע ולהפעיל את Multidex כאן. הדרישה הזו רלוונטית לאפליקציות שבהן minSdkVersion מוגדר ל-20 ומטה. בנוסף, צריך להוסיף compileOptions חדש כדי לציין את פרטי התאימות של גרסת 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.3.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'androidx.media3:media3-exoplayer-ima:1.3.1'

    ...
}

הוסף את הרשאות המשתמש הנדרשות על ידי IMA SDK כדי לבקש מודעות.

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>

הוספה של הצהרות Intent

אם האפליקציה שלך מטרגטת ל-Android 11 (רמת API 30) ואילך, לגרסה הנוכחית ולגרסאות האחרונות של IMA SDK נדרשת הצהרת כוונה מפורשת כדי לפתוח קישורים לדפי אינטרנט אחרים. צריך להוסיף את קטע הקוד הבא לקובץ המניפסט של האפליקציה כדי לאפשר קליקים על המודעות (משתמשים שלוחצים על הלחצן למידע נוסף).

הערה: גרסאות עתידיות של IMA SDK יכללו באופן אוטומטי את ההצהרות האלה וימוזגו עם קובץ המניפסט של האפליקציה.

  <?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. יצירת מאגר התגים של ממשק המשתמש של המודעה

כדי ליצור את התצוגה שתשמש כ-ExoPlayer PlayerView, יוצרים אובייקט StyledPlayerView עם מזהה מתאים. בנוסף, צריך לשנות את הערך בשדה androidx.constraintlayout.widget.ConstraintLayout לערך 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. מוסיפים את כתובת ה-URL של התוכן ואת כתובת ה-URL של תג המודעה לבקשה להצגת מודעות

צריך להוסיף רשומות אל strings.xml כדי לאחסן את כתובת ה-URL של התוכן ואת כתובת ה-URL של תג מודעה VAST.

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. ייבוא של תוסף IMA של ExoPlayer

הוסף את הצהרות הייבוא של התוסף ExoPlayer. לאחר מכן מעדכנים את המחלקה MainActivity כדי להרחיב את Activity, על ידי הוספת משתנים פרטיים עבור PlayerView, SimpleExoPlayer ו-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. יצירת מכונה של adsLoader

כדי ליצור אובייקט adsLoader חדש עם כתובת ה-URL של תג המודעה, מחליפים את השיטה onCreate ומוסיפים את הקצאות המשתנים הנדרשות.

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. אתחול ושחרור הנגן

הוספת שיטות לאתחול ולשחרור הנגן. בשיטת האתחול, יוצרים את השדה SimpleExoPlayer. לאחר מכן, יוצרים את השדה AdsMediaSource ומגדירים אותו בנגן.

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. טיפול באירועי שחקנים

לבסוף, יוצרים קריאות חוזרות (callback) לאירועי מחזור החיים של השחקן:

• onStart
• onResume
• onStop
• onPause
• onDestroy

הערה: בקוד לדוגמה נעשה שימוש ב-onStart/onStop ל-Android SDK מגרסה 24 ואילך וב-onResume/onPause לגרסאות שקודמות ל-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();
  }

  ...

}

זהו! הבקשה שלך להצגת מודעות מתבצעת עכשיו באמצעות IMA SDK. כדי לקבל מידע על תכונות נוספות של SDK, אפשר לעיין במדריכים האחרים או בדוגמאות ב-GitHub.