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

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

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

لعرض واجهة مستخدم مخصّصة، عليك أولاً إيقاف واجهة المستخدم التلقائية للإعلان. لتنفيذ هذا الإجراء، يجب الاتصال بـ 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 لنموذج العلامة هذا ولصقه في عملية تنفيذ إعلانات الوسائط التفاعلية.
لا يمكنني إيقاف واجهة المستخدم التلقائية.
تأكد من الاتصال بـ AdsRenderingSettings.setDisableUi() وتمريره إلى AdsManager. تأكّد من أنّ Ad.isUiDisabled() يعرض true. بالإضافة إلى ذلك، يجب تفعيل شبكتك في "مدير الإعلانات" لإيقاف واجهة مستخدم الإعلانات. في حال تفعيلك، يحتوي نموذج عرض إعلانات الفيديو (VAST) على Extension على النحو التالي: 
<Extension type="uiSettings">
<UiHideable>1</UiHideable>
</Extension>
إذا استمرّت المشكلة، يُرجى مراجعة مدير حسابك للتأكّد من تفعيلك. تتطلب بعض أنواع الإعلانات واجهة مستخدم محددة، ويتم عرض هذه الإعلانات بقيمة <UiHideable> تساوي 0. إذا واجهت هذه المشكلة، سيحتاج فريق عدد الزيارات إلى إجراء تغييرات لضمان عدم عرض أنواع الإعلانات هذه.