واجهة مستخدم مخصّصة تتضمّن حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لنظام التشغيل Android

يوضّح هذا الدليل كيفية تنفيذ واجهة المستخدم المخصّصة باستخدام حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) لنظام التشغيل Android. ولإجراء ذلك، عليك إيقاف واجهة المستخدم التلقائية وإعداد واجهة مستخدم مخصّصة جديدة، ثمّ تعبئة واجهة المستخدم الجديدة بمعلومات الإعلانات التي تم الحصول عليها من حزمة تطوير البرامج (SDK).

ملاحظة: يجب تفعيل حسابك على "إعلانات Google" لاستخدام هذه الميزة. يُرجى التواصل مع مدير حسابك للحصول على مزيد من المعلومات.

ملاحظة: يستند هذا المثال إلى IMA BasicExample لنظام التشغيل Android.

إيقاف واجهة مستخدِم الإعلان

لعرض واجهة مستخدم مخصّصة، عليك أولاً إيقاف واجهة مستخدم الإعلان التلقائية. لإجراء ذلك، يمكنك استدعاء AdsRenderingSettings.setDisableUi() ثم تمرير AdsRenderingSettings إلى AdsManager.init():

MyActivity.java

ImaSdkFactory mSdkFactory = ImaSdkFactory.getInstance();
AdsManager mAdsManager;

@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) {
    mAdsManager = adsManagerLoadedEvent.getAdsManager();

    ...
    AdsRenderingSettings settings = mSdkFactory.createAdsRenderingSettings();
    settings.setDisableUi(true);
    mAdsManager.init(settings);
}

بعد ذلك، كلما أردت تحديد ما إذا كنت تريد عرض واجهة المستخدم المخصّصة، تحقّق مما إذا كان هناك إعلان، واتصل بـ Ad.isUiDisabled() للتأكّد من إيقاف واجهة مستخدم الإعلان الافتراضية.

عرض واجهة مستخدم مخصّصة

بعد إيقاف واجهة المستخدم التلقائية، تكون الخطوة التالية هي عرض واجهة مستخدم مخصّصة للإعلان. في هذا المثال، أضِف RelativeLayout جديدًا إلى تنسيق مشغّل الفيديو الحالي، ثم أظهِر هذا التنسيق عند عرض إعلان وأخفِه عندما لا يتم عرض إعلانات.

أضِف ما يلي إلى ملف تنسيق المقتطف:

fragment_video.xml

<com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer
    android:id="@+id/sampleVideoPlayer"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
<RelativeLayout
        android:id="@+id/customUi"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:visibility="invisible">
                <TextView
                    android:id="@+id/adCounter"
                    android:layout_width="wrap_content"
                    android:layout_height="wrap_content"
                    android:background="@android:color/holo_green_light"
                    android:layout_alignParentTop="true"
                    android:layout_alignParentLeft="true"
                    android:text="@string/ad_counter" />
                <Button
                  android:id="@+id/learnMoreButton"
                  android:background="@android:color/holo_green_light"
                  android:layout_width="wrap_content"
                  android:layout_height="wrap_content"
                  android:layout_alignParentTop="true"
                  android:text="@string/learn_more"
                  android:layout_alignParentRight="true" />
                <Button
                  android:id="@+id/skipButton"
                  android:background="@android:color/holo_green_light"
                  android:layout_width="wrap_content"
                  android:layout_height="wrap_content"
                  android:layout_alignParentBottom="true"
                  android:text="@string/skip_ad"
                  android:enabled="false"
                  android:layout_alignParentRight="true" />
</RelativeLayout>

بعد ذلك، أضِف الرمز لاستخدام واجهة المستخدم المخصّصة إلى Activity. لتعديل واجهة المستخدم، أنشئ موقّتًا Handler وRunnable يعمل عليه.

MyActivity.java

// The view containing the custom UI.
private View mCustomUi;
// The timer handler.
private Handler mTimerHandler = new Handler();

// The Runnable that runs your custom UI update loop.
private Runnable mTimerRunnable = new Runnable() {
    @Override
    public void run() {
        updateCustomUi();
        mTimerHandler.postDelayed(this, 500);
    }
};

@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container,
                Bundle savedInstanceState) {
...
    mCustomUi = rootView.findViewById(R.id.customUi);
    mAdCounterUi = (TextView) rootView.findViewById(R.id.adCounter);
}

@Override
public void onAdEvent(AdEvent adEvent) {
    ...
    switch (adEvent.getType()) {
        ...
            case STARTED:
            // Start your update loop.
            mTimerHandler.post(mTimerRunnable);
            Break;
                ...
        case COMPLETED:
            mCustomUi.setVisibility(View.INVISIBLE);
            mTimerHandler.removeCallbacks(mTimerRunnable);
            ...
    }
}

@Override
public void onPause() {
...
    // Stop ad UI update loop.
    mTimerHandler.removeCallbacks(mTimerRunnable);
}

@Override
Public void onResume() {
...
    // Start ad UI update loop.
    mTimerHandler.post(mTimerRunnable);
}

عداد الإعلانات وزر التخطّي

حدِّد الآن دالة updateCustomUi() لملء واجهة المستخدم بمعلومات الإعلانات. تختلف التفاصيل حسب شكل الإعلان، ولكن غالبًا ما يتم تضمين عداد الإعلانات وزر أو عداد للتخطّي إذا كان الإعلان قابلاً للتخطّي. أضِف ما يلي:

MyActivity.java

private void updateCustomUi() {
    // Runs from the update loop to update the custom UI.
    Ad ad = mAdsManager.getCurrentAd();
    if (ad != null && ad.isUiDisabled()) {
        // Show the UI.
        Log.i(LOGTAG, "UI disabled, show custom UI!");
        AdPodInfo podInfo = ad.getAdPodInfo();
        VideoProgressUpdate update = mAdsManager.getAdProgress();
        SimpleDateFormat format = new SimpleDateFormat("mm:ss", Locale.US);

        // Handle ad counter.
        String adProgress = format.format(
                (update.getDuration() - update.getCurrentTime()) * 1000);
        String adUiString = String.format(
                Locale.US, "Ad %d of %d (%s)", podInfo.getAdPosition(),
                podInfo.getTotalAds(), adProgress);
        mAdCounterUi.setText(adUiString);

        // Handle skippable ads.
        if (ad.isSkippable()) {
            if (update.getCurrentTime() >= ad.getSkipTimeOffset()) {
                // Allow skipping.
                mSkipButton.setText(getString(R.string.skip_ad));
                mSkipButton.setEnabled(true);
            } else {
                String skipString = String.format(
                        Locale.US, "You can skip this ad in %d",
                        (int) (ad.getSkipTimeOffset() -
                                update.getCurrentTime()));
                mSkipButton.setText(skipString);
                mSkipButton.setEnabled(false);
            }
            mSkipButton.setVisibility(View.VISIBLE);
        } else {
            mSkipButton.setVisibility(View.INVISIBLE);
        }
        mCustomUi.setVisibility(View.VISIBLE);
        mCustomUi.bringToFront();
    } else {
        // Hide the UI.
        mCustomUi.setVisibility(View.INVISIBLE);
        mTimerHandler.removeCallbacks(mTimerRunnable);
    }
}

في الرمز السابق، بعد التحقّق ممّا إذا كان هناك إعلان واستخدام الإجراء Ad.isUiDisabled() للتحقّق من إيقاف واجهة مستخدِم الإعلان التلقائية، استخدِم الإجراء Ad.getAdPodInfo() وAdsManager.getAdProgress() للعثور على موضع الإعلان في مجموعة الإعلانات المتسلسلة ومستوى تقدّم الإعلان. بالنسبة إلى الإعلانات القابلة للتخطّي، يجب عرض عدّاد للتخطّي إذا لم يكن بإمكانك تخطّي الإعلان بعد، وإلا يجب عرض زرّ للتخطّي. في ما يلي ملخّص لمعلومات الإعلانات الشائعة والمكالمات المرتبطة بها:

معلومات	الاتصال
الإعلان الحالي في مجموعة الإعلانات	Ad.getAdPodInfo().getAdPosition()
إجمالي الإعلانات في مجموعة الإعلانات المتسلسلة	Ad.getPodInfo().getTotalAds()
ما إذا كان الإعلان قابلاً للتخطّي	Ad.isSkippable()
الثواني المتبقية قبل أن يصبح بإمكانك تخطّي الإعلان	Ad.getSkipTimeOffset() - AdsManager.getAdProgress().getCurrentTime()
الثواني المتبقية في الإعلان	(AdsManager.getAdProgress().getDuration() - AdsManager.getAdProgress().getCurrentTime()) * 1000

من المفترض أن يؤدي النقر على الزر تخطّي الإعلان إلى تخطّي الإعلان، لذا عليك إعداد ذلك، بالإضافة إلى الزر مزيد من المعلومات:

MyActivity.java

@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container,
                Bundle savedInstanceState) {
...
mCustomUi = rootView.findViewById(R.id.customUi);
mAdCounterUi = (TextView) rootView.findViewById(R.id.adCounter);

// Set up the 'learn more' button handler for the custom UI.
mLearnMoreButton = (Button) rootView.findViewById(R.id.learnMoreButton);
mLearnMoreButton.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View view) {
        // Only works if the UI has been disabled.
        mAdsManager.clicked();
    }
});

// Set up the skip button handler for the custom UI.
mSkipButton = (Button) rootView.findViewById(R.id.skipButton);
mSkipButton.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View view) {
        mAdsManager.skip();
    }
});

يجب إيقاف واجهة المستخدم لكي تعمل AdsManager.clicked().

تحديد المشاكل وحلّها

هل لديك نموذج علامة مفعّل لإيقاف واجهة مستخدِم الإعلان؟

يمكنك نسخ عنوان URL الخاص بهذه علامة النموذج ولصقه في عملية تنفيذ IMA.

لا يمكنني إيقاف واجهة المستخدم التلقائية.

تأكَّد من أنّك تتصل بـ AdsRenderingSettings.setDisableUi() و تمرّر الطلب إلى AdsManager. تأكَّد من أنّ Ad.isUiDisabled() يعرض true. بالإضافة إلى ذلك، يجب تفعيل شبكتك في "مدير إعلانات Google" لإيقاف واجهة مستخدم إعلانات. إذا كان لديك إذن، ستتضمّن ملفّات VAST Extension على النحو التالي:

<Extension type="uiSettings">
<UiHideable>1</UiHideable>
</Extension>

إذا كنت لا تزال تواجه مشكلة، يُرجى التواصل مع مدير حسابك للتأكّد من تفعيل هذه الميزة. تتطلّب بعض أنواع الإعلانات واجهة مستخدم معيّنة، وتعرض هذه الإعلانات قيمة <UiHideable> تساوي 0. إذا واجهت هذا الخطأ، على فريق الإحالة الناجحة إجراء تغييرات للتأكّد من عدم عرض أنواع الإعلانات هذه.