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

במדריך הזה מוסבר איך להטמיע ממשק משתמש מותאם אישית באמצעות IMA SDK ל-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() כדי לבדוק ש-UI ברירת המחדל של המודעה הושבת, מפעילים את הפונקציות Ad.getAdPodInfo() ו-AdsManager.getAdProgress() כדי למצוא את המיקום של המודעה ב-pod ואת ההתקדמות שלה. במודעות שניתן לדלג עליהן, כדאי להציג ספירת זמן לדילוג אם עדיין אי אפשר לדלג על המודעה. אחרת, כדאי להציג כפתור לדילוג. ריכזנו כאן סיכום של פרטי מודעות נפוצים והקריאות המשויכות:

מידע התקשרות
המודעה הנוכחית ברצף המודעות 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. בנוסף, כדי להשבית ממשק משתמש של מודעה, צריך להפעיל את הרשת ב-Ad Manager. אם האפשרות מופעלת, קובץ ה-VAST מכיל את הקוד Extension שנראה כך: 
<Extension type="uiSettings">
<UiHideable>1</UiHideable>
</Extension>
 אם הבעיה נמשכת, כדאי לפנות למנהל החשבון כדי לוודא שהחשבון שלכם מופעל. סוגים מסוימים של מודעות דורשים ממשק משתמש ספציפי. המודעות האלה מחזירות את הערך 0 עבור <UiHideable>. אם נתקלתם בבעיה כזו, צוות ניהול התנועה יצטרך לבצע שינויים כדי לוודא שסוגי המודעות האלה לא יוצגו.