Exoplayer IMA uzantısını kullanmaya başlayın

IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları, VAST ile uyumlu herhangi bir reklam sunucusundan reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA istemci tarafı SDK'larıyla, SDK reklam oynatmayı yönetirken içerik videosunun oynatılmasını kontrol edebilirsiniz. Reklamlar, uygulamanın içerik video oynatıcının üstüne yerleştirilmiş ayrı bir video oynatıcıda oynatılır.

Bu kılavuzda, ExoPlayer IMA uzantısı kullanılarak IMA SDK'sının boş bir Android Studio projesine nasıl entegre edileceği gösterilmektedir. Tamamlanmış bir örnek entegrasyonu görüntülemek veya takip etmek istiyorsanız GitHub'dan BasicExample dosyasını indirin.

Not: Diğer platformlarla entegrasyon veya IMA DAI SDK'larının kullanımı hakkında bilgi edinmek için Interactive Media Ads SDK'ları başlıklı makaleyi inceleyin.

IMA istemci tarafına genel bakış

IMA'yı istemci tarafında uygulamak, bu kılavuzda gösterilen dört ana SDK bileşenini içerir:

• AdDisplayContainer: IMA'nın reklam kullanıcı arayüzü öğelerini nerede oluşturduğunu ve Aktif Görüntüleme ile Open Measurement dahil olmak üzere görüntülenebilirliği ölçtüğünü belirten bir kapsayıcı nesnesi.
• AdsLoader: Reklam isteyen ve reklam isteği yanıtlarından gelen etkinlikleri işleyen bir nesne. Yalnızca bir reklam yükleyicisi oluşturmanız gerekir. Bu reklam yükleyici, uygulamanın ömrü boyunca yeniden kullanılabilir.
• AdsRequest: Reklam isteğini tanımlayan bir nesne. Reklam istekleri, VAST reklam etiketinin URL'sini ve reklam boyutları gibi ek parametreleri belirtir.
• AdsManager: Reklam isteğine verilen yanıtı içeren, reklam oynatmayı kontrol eden ve SDK tarafından tetiklenen reklam etkinliklerini dinleyen bir nesne.

Not: ExoPlayer IMA uzantısı bu kılavuzda IMA SDK'sını sarmaladığından, hem AdsRequest hem de AdsManager kullanılıyor ancak açıkça çağrılmıyor.

Ön koşullar

Başlamadan önce Android Studio 3.0 veya sonraki bir sürüme sahip olmanız gerekir.

1. Yeni bir Android Studio projesi oluşturma

Android Studio projenizi oluşturmak için aşağıdaki adımları uygulayın:

1. Android Studio'yu başlatın.
2. Yeni bir Android Studio projesi başlat'ı seçin.
3. Projenizi seçin sayfasında Boş Etkinlik şablonunu seçin.
4. İleri'yi tıklayın.
5. Projenizi yapılandırın sayfasında projenize bir ad verin ve dil olarak Java'yı seçin.
   Not: IMA SDK, Kotlin ile uyumludur. Ancak bu kılavuzda ele alınan örnekte Java kullanılmaktadır.
6. Son'u tıklayın.

2. ExoPlayer IMA uzantısını projenize ekleme

Öncelikle, uygulama düzeyindeki build.gradle dosyasında, uzantının bağımlılıklarını bölüme ekleyin. ExoPlayer IMA uzantısının boyutu nedeniyle burada multidex'i uygulayıp etkinleştirin. Bu, minSdkVersion değeri 20 veya daha düşük olan uygulamalar için gereklidir. Ayrıca, Java sürümü uyumluluk bilgilerini belirtmek için yeni compileOptions ekleyin.

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'

    ...
}

Reklam istemek için IMA SDK'nın gerektirdiği kullanıcı izinlerini ekleyin.

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 beyanları ekleme

Uygulamanız Android 11'i (API düzeyi 30) veya sonraki sürümleri hedefliyorsa IMA SDK'sının mevcut ve son sürümleri, web bağlantılarını açma amacıyla açık bir beyan gerektirir. Reklam tıklamalarını (kullanıcıların Daha fazla bilgi düğmesini tıklaması) etkinleştirmek için uygulamanızın manifest dosyasına aşağıdaki snippet'i ekleyin.

Not: IMA SDK'sının gelecekteki sürümleri bu beyanları otomatik olarak içerecek ve uygulamanızın manifest dosyasıyla birleştirilecektir.

  <?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. Reklam kullanıcı arayüzü kapsayıcısını oluşturma

Uygun bir kimliğe sahip bir StyledPlayerView nesnesi oluşturarak ExoPlayer PlayerView olarak kullanılacak görünümü oluşturun. Ayrıca androidx.constraintlayout.widget.ConstraintLayout değerini LinearLayout olarak değiştirin.

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. Reklam isteği için içerik URL'nizi ve reklam etiketi URL'nizi ekleyin

İçerik URL'nizi ve VAST reklam etiketi URL'nizi depolamak için strings.xml alanına girişler ekleyin.

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 uzantısını içe aktarma

ExoPlayer uzantısı için içe aktarma ifadelerini ekleyin. Ardından, PlayerView, SimpleExoPlayer ve ImaAdsLoader için özel değişkenler ekleyerek MainActivity sınıfını Activity'ü genişletecek şekilde güncelleyin.

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 örneği oluşturma

Reklam etiketi URL'sini içeren yeni bir adsLoader nesnesi oluşturmak için onCreate yönteminin üzerine yazın ve gerekli değişken atamalarını ekleyin.

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. Oynatıcıyı başlatma ve serbest bırakma

Oynatıcıyı başlatmak ve serbest bırakmak için yöntemler ekleyin. initialize yönteminde SimpleExoPlayer öğesini oluşturun. Ardından AdsMediaSource öğesini oluşturun ve oynatıcıya ayarlayın.

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. Oyuncu etkinliklerini işleme

Son olarak, oynatıcının yaşam döngüsü etkinlikleri için geri aramalar oluşturun:

• onStart
• onResume
• onStop
• onPause
• onDestroy

Not: Örneğin kodunda, Android SDK'sının 24 ve sonraki sürümleri için onStart/onStop, 24'ten önceki sürümler için ise onResume/onPause kullanılır.

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

  ...

}

İşte bu kadar. Artık IMA SDK ile reklam isteğinde bulunuyor ve reklamları görüntülüyorsunuz. Diğer SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örneklere göz atın.