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

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

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

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

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

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

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

לפני שמתחילים, צריך להתקין את Android Studio בגרסה 3.0 ואילך.

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

כדי ליצור פרויקט ב-Android Studio:

  1. פותחים את Android Studio.
  2. בוחרים באפשרות Start a new Android Studio project (התחלת פרויקט חדש ב-Android Studio).
  3. בדף Choose your project, בוחרים בתבנית Empty Activity.
  4. לוחצים על הבא.
  5. בדף Configure your project, נותנים שם לפרויקט ובוחרים את Java כשפה.
  6. לוחצים על סיום.

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

קודם כול, בקובץ build.gradle ברמת האפליקציה, מוסיפים את ייבוא התוסף לקטע של יחסי התלות. בגלל הגודל של התוסף ExoPlayer IMA, צריך להטמיע ולהפעיל את 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>

הוספת הצהרות כוונות

אם האפליקציה שלכם מטרגטת ל-Android 11 (רמת API 30) ואילך, הגרסאות הנוכחיות והעדכניות של 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. יצירת הקונטיינר של ממשק המשתמש של המודעה

יוצרים את התצוגה שתשמש כ-PlayerView של ExoPlayer על ידי יצירת אובייקט 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. ייבוא התוסף של ExoPlayer IMA

מוסיפים את הצהרות הייבוא של תוסף 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

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

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 בשיטת initialize. לאחר מכן יוצרים את 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. טיפול באירועי שחקנים

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

  • onStart
  • onResume
  • onStop
  • onPause
  • onDestroy
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.