IMA SDK ادغام تبلیغات چندرسانه ای را در وب سایت ها و برنامه های شما آسان می کند. IMA SDK میتواند از هر سرور تبلیغاتی سازگار با VAST آگهی درخواست کند و پخش آگهی را در برنامههای شما مدیریت کند. با SDK های سمت سرویس گیرنده IMA، کنترل پخش ویدیوی محتوا را حفظ می کنید، در حالی که SDK پخش آگهی را کنترل می کند. تبلیغات در یک پخش کننده ویدیوی جداگانه که در بالای پخش کننده ویدیوی محتوای برنامه قرار دارد پخش می شود.
این راهنما نحوه ادغام IMA SDK را با استفاده از افزونه ExoPlayer IMA در یک پروژه خالی Android Studio نشان می دهد. اگر میخواهید نمونه یکپارچهسازی کامل شده را مشاهده یا دنبال کنید، BasicExample را از GitHub دانلود کنید.
نمای کلی سمت مشتری IMA
پیاده سازی سمت مشتری IMA شامل چهار جزء اصلی SDK است که در این راهنما نشان داده شده است:
-
AdDisplayContainer
: یک شی کانتینری که مشخص می کند IMA عناصر رابط کاربری تبلیغات را در کجا رندر می کند و قابلیت مشاهده را اندازه گیری می کند، از جمله نمایش فعال و اندازه گیری باز . -
AdsLoader
: شیئی که درخواست تبلیغات می کند و رویدادها را از پاسخ های درخواست تبلیغات مدیریت می کند. شما باید فقط یک بارکننده تبلیغات را نمونه برداری کنید، که می تواند در طول عمر برنامه مجددا استفاده شود. -
AdsRequest
: شیئی که درخواست تبلیغات را تعریف می کند. درخواستهای تبلیغات نشانی اینترنتی تگ تبلیغات VAST و همچنین پارامترهای اضافی مانند ابعاد آگهی را مشخص میکنند. -
AdsManager
: شیئی که حاوی پاسخ به درخواست تبلیغات است، پخش آگهی را کنترل می کند و به رویدادهای تبلیغاتی که توسط SDK اجرا می شود گوش می دهد.
پیش نیازها
قبل از شروع، به Android Studio نسخه 3.0 یا بالاتر نیاز دارید.
1. یک پروژه اندروید استودیو جدید ایجاد کنید
برای ایجاد پروژه Android Studio خود، مراحل زیر را انجام دهید:
- Android Studio را راه اندازی کنید.
- شروع پروژه جدید Android Studio را انتخاب کنید.
- در صفحه Choose your project ، قالب Empty Activity را انتخاب کنید.
- روی Next کلیک کنید.
- در صفحه Configure your project ، نام پروژه خود را گذاشته و جاوا را برای زبان انتخاب کنید.
- روی Finish کلیک کنید.
2. پسوند ExoPlayer IMA را به پروژه خود اضافه کنید
ابتدا در فایل build.gradle در سطح برنامه، import برای پسوند را به بخش وابستگی ها اضافه کنید. به دلیل اندازه پسوند ExoPlayer IMA، multidex را در اینجا پیاده سازی و فعال کنید. این برای برنامه هایی با minSdkVersion
تنظیم شده روی 20 یا کمتر ضروری است. همچنین، برای تعیین اطلاعات سازگاری نسخه جاوا 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' }
3. ظرف رابط کاربری تبلیغات را ایجاد کنید
با ایجاد 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>
4. پسوند ExoPlayer IMA را وارد کنید
دستورهای import را برای پسوند 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;
سپس، کلاس MainActivity
را برای گسترش Activity
با افزودن متغیرهای خصوصی برای PlayerView
، ExoPlayer
، ImaAdsLoader
و ImaSdkSettings
به روز کنید:
/** 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;
5. یک نمونه adsLoader
ایجاد کنید
روش onCreate
بازنویسی کنید و تخصیص متغیرهای مورد نیاز را اضافه کنید تا یک شی adsLoader
جدید با URL تگ آگهی ایجاد کنید.
@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(); }
متد buildAdEventListener()
ایجاد کنید تا یک شی AdEventListener
را برای ثبت رویدادهای IMA برای اشکال زدایی بازگردانید. افزونه 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); }; }
روش کمکی getImaSdkSettings()
ایجاد کنید تا یک شی ImaSdkSettings
را برای تنظیم تنظیمات IMA SDK برگردانید:
private ImaSdkSettings getImaSdkSettings() { if (imaSdkSettings == null) { imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings(); // Set any IMA SDK settings here. } return imaSdkSettings; }
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); }
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(); }
اکنون با موفقیت در حال درخواست و نمایش تبلیغات با IMA SDK هستید. برای آشنایی با ویژگیهای پیشرفتهتر، راهنماهای دیگر یا نمونههای موجود در GitHub را کاوش کنید.