ממשק משתמש מותאם אישית עם IMA SDK ל-Android

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

הערה: כדי שתוכלו להשתמש בתכונה הזו, עליכם להפעיל את חשבון Google Ad Manager שלכם. למידע נוסף אפשר לפנות למנהל החשבון.

הערה: הדוגמה הזו מבוססת על 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() כדי לברר את מיקום המודעה ב-pod ואת ההתקדמות של המודעה. במודעות שניתן לדלג עליהן, עדיף להציג מונה דילוג אם אי אפשר עדיין לדלג על המודעה. אם לא, כדאי להציג לחצן דילוג. הנה סיכום של מידע נפוץ על מודעות וקריאות משויכות:

מידע	התקשרות
מודעה נוכחית ב-Pod	Ad.getAdPodInfo().getAdPosition()
סה"כ מודעות ב-pod	Ad.getPodInfo().getTotalAds()
האם המודעה ניתנת לדילוג	Ad.isSkippable()
מספר שניות עד שניתן לדלג על המודעה	Ad.getSkipTimeOffset() - AdsManager.getAdProgress().getCurrentTime()
שניות שנותרו במודעה	(AdsManager.getAdProgress().getDuration() - AdsManager.getAdProgress().getCurrentTime()) * 1000

לחיצה על הלחצן Skip Ad (דילוג על המודעה) אמורה לדלג על המודעה, ולכן צריך להגדיר אותו בנוסף ללחצן למידע נוסף:

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. בנוסף, צריך להפעיל את הרשת ב-Ad Manager כדי להשבית ממשק משתמש של מודעות. אם האפשרות מופעלת, ה-VAST שלכם מכיל Extension שנראה כך:

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

אם אתם עדיין נתקלים בבעיות, כדאי לבדוק עם מנהל החשבון אם האפשרות הזו מופעלת. סוגי מודעות מסוימים דורשים ממשק משתמש ספציפי. מודעות אלה מוחזרות עם הערך <UiHideable> של 0. במקרה כזה, צוות ניהול הטראפיק יצטרך לבצע שינויים כדי להבטיח שסוגי המודעות האלה לא יוצגו.