התחל בעבודה

השלב הראשון הוא להוסיף את Android PAL SDK לאפליקציה.

הוספת Android PAL SDK כספרייה

החל מגרסה 18.0.0, ה-SDK של PAL מתארח במאגר Maven של Google, וניתן להוסיף אותו לאפליקציה באופן הבא:

app/build.gradle

...
dependencies {
    implementation 'com.google.android.gms:play-services-pal:22.0.0'
    ...
}

לחלופין, אפשר להוריד את PAL SDK ממאגר Maven של Google ולהוסיף אותו לאפליקציה באופן ידני.

יצירת קוד חד-פעמי (nonce)

'nonce' הוא מחרוזת מוצפנת אחת שנוצרת על ידי PAL באמצעות NonceLoader. ב-PAL SDK נדרש שהבקשה החדשה להעברת הנתונים תכלול קוד חד-פעמי (nonce) שנוצר לאחרונה. עם זאת, אפשר לעשות שימוש חוזר במספרים חד-פעמיים במספר בקשות להצגת מודעות באותו מקור. כדי ליצור קוד חד-פעמי באמצעות PAL SDK, מבצעים שינויים ב-MyActivity.java. כדי לראות אפליקציה לדוגמה שמשתמשת ב-PAL ליצירת מספר חד-פעמי, תוכלו להוריד את הדוגמה ל-Android מ-GitHub.

קודם צריך לייבא את PAL SDK, ליצור כמה מאפיינים פרטיים לאחסון הערכים של NonceLoader ו-NonceManager, ואז לאתחל את NonceLoader.

מומלץ ליצור רק מופע אחד של הכיתה NonceLoader לכל סשן משתמש באפליקציה, אלא אם באפליקציה יש כמה דפים או מבנים מקבילים. כך המתאמים של הדפים (&correlator) לא ישתנו במהלך החיים של הדף או הסשן של המשתמש באפליקציה. עדיין יש לכם שליטה על המתאמים של הסטרימינג (&scor), שצריך לאפס פעם אחת לכל סטרימינג חדש.

כדי שתכונות כמו הגבלת התדירות והחרגה תחרותית יפעלו כראוי, כל בקשות המודעות מאותו מקור צריכות לשתף את אותו ערך NonceLoader ואותו ערך של מתאם הסטרימינג.

import android.app.Activity;
import android.os.Bundle;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;

import java.util.HashSet;
import java.util.Set;

public class MainActivity extends Activity {
...
  private NonceLoader nonceLoader;
  private NonceManager nonceManager = null;
  private ConsentSettings consentSettings;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // The default value for allowStorage() is false, but can be
    // changed once the appropriate consent has been gathered. The
    // getConsentToStorage() method is a placeholder for the publisher's own
    // method of obtaining user consent, either by integrating with a CMP or
    // based on other methods the publisher chooses to handle storage consent.

    boolean isConsentToStorage = getConsentToStorage();

    videoView = findViewById(R.id.video_view);
    videoView.setOnTouchListener(this::onVideoViewTouch);

    consentSettings = ConsentSettings.builder()
            .allowStorage(isConsentToStorage)
            .build();

    // It is important to instantiate the NonceLoader as early as possible to
    // allow it to initialize and preload data for a faster experience when
    // loading the NonceManager. A new NonceLoader will need to be instantiated
    //if the ConsentSettings change for the user.
    nonceLoader = new NonceLoader(this, consentSettings);
    ...
  }

בשלב הבא, יוצרים פונקציה להפעלת יצירת קוד חד-פעמי. צריך רק nonce אחד לכל הבקשות להצגת מודעות בהפעלה של סטרימינג יחיד. למטרות בדיקה, אפשר להפעיל את הפונקציה הזו בלחיצה על לחצן באפליקציית הבדיקה. הפרמטרים NonceRequest שמוגדרים כאן הם פרמטרים לדוגמה. מומלץ להגדיר את הפרמטרים על סמך מאפייני האפליקציה שלכם.

הפונקציה הזו מפעילה יצירת nonce באופן אסינכרוני, לכן צריך להטמיע AsyncTask כדי לטפל בהצלחה או בכישלון של בקשת ה-nonce:

public void generateNonceForAdRequest() {
  Set supportedApiFrameWorksSet = new HashSet();
  // The values 2, 7, and 9 correspond to player support for VPAID 2.0,
  // OMID 1.0, and SIMID 1.1.
  supportedApiFrameWorksSet.add(2);
  supportedApiFrameWorksSet.add(7);
  supportedApiFrameWorksSet.add(9);

  NonceRequest nonceRequest = NonceRequest.builder()
      .descriptionURL("https://example.com/content1")
      .iconsSupported(true)
      .omidPartnerVersion("6.2.1")
      .omidPartnerName("Example Publisher")
      .playerType("ExamplePlayerType")
      .playerVersion("1.0.0")
      .ppid("testPpid")
      .sessionId("Sample SID")
      .supportedApiFrameworks(supportedApiFrameWorksSet)
      .videoPlayerHeight(480)
      .videoPlayerWidth(640)
      .willAdAutoPlay(true)
      .willAdPlayMuted(false)
      .build();
  NonceCallbackImpl callback = new NonceCallbackImpl();
  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(callback)
      .addOnFailureListener(callback);
}

private class NonceCallbackImpl implements OnSuccessListener<NonceManager>, OnFailureListener {
  @Override
  public void onSuccess(NonceManager manager) {
    nonceManager = manager;
    String nonceString = manager.getNonce();
    Log.i("PALSample", "Generated nonce: " + nonceString);
    // from here you would trigger your ad request and move on to initialize content
  }

  @Override
  public void onFailure(Exception error) {
    Log.e("PALSample", "Nonce generation failed: " + error.getMessage());
  }
}

אחרי שיוצרים מנהל אסימונים חד-פעמיים, אפשר לאחזר את האסימון החד-פעמי בכל שלב באמצעות הפקודה nonceManager.getNonce().

צירוף nonce לבקשה להצגת מודעה

כדי להשתמש במזהה החד-פעמי שנוצר, צריך לצרף לתג המודעה פרמטר givn ואת ערך המזהה החד-פעמי לפני שליחת הבקשות להצגת מודעות.

/**
 * The ad tag for your ad request, for example:
 * https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external\
 * /single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1\
 * &cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=
 *
 * For more sample ad tags, see
 * developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
 */
private static final String DEFAULT_AD_TAG = "Your ad tag";
...
@Override
public void onSuccess(NonceManager manager) {
  nonceManager = manager;
  String nonceString = manager.getNonce();
  Log.i("PALSample", "Generated nonce: " + nonceString);
  // Append the nonce to the ad tag URL.
  makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
}

מעקב אחר אירועי הפעלה

לבסוף, צריך להטמיע פונקציות טיפול באירועים שונות בנגן. למטרות בדיקה, אפשר לצרף אותם לאירועי לחיצה על לחצן, אבל בהטמעה אמיתית הם יופעלו על ידי אירועי הנגן המתאימים:

public void sendAdClick() {
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

public void sendPlaybackStart() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

public void sendPlaybackEnd() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendTouch(e);
  }
}

זה הזמן להפעיל כל פונקציה בהטמעה:

  • sendPlaybackStart(): כשסשן ההפעלה של הסרטון מתחיל
  • sendPlaybackEnd(): בסיום סשן ההפעלה של הסרטון
  • sendAdClick(): בכל פעם שהצופה לוחץ על מודעה
  • sendTouch(): בכל אינטראקציה עם הנגן באמצעות מגע

(אופציונלי) שליחת אותות מ-Google Ad Manager דרך שרתי מודעות של צד שלישי

כשמגדירים את שרת המודעות של הצד השלישי לפעול עם Google Ad Manager, צריך לעיין במסמכי העזרה של השרת כדי לתעד את ערך ה-nonce ולהעביר אותו בכל בקשה להצגת מודעה. הדוגמה שצוינה היא של כתובת URL לבקשת מודעה, שכוללת את הפרמטר nonce. הפרמטר nonce מופץ מ-PAL SDK, דרך השרתים המקשרים ואז אל Ad Manager, וכך מאפשר לייעל את המונטיזציה.

מגדירים את שרת המודעות של הצד השלישי כך שיכלול את המזהה החד-פעמי בבקשה של השרת אל Ad Manager. דוגמה לתג מודעה שמוגדר בתוך שרת המודעות של הצד השלישי:

'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'

פרטים נוספים זמינים במדריך להטמעה בצד השרת של Google Ad Manager.

מערכת Ad Manager מחפשת את givn= כדי לזהות את ערך ה-nonce. שרת המודעות של הצד השלישי צריך לתמוך במאקרו משלו, כמו %%custom_key_for_google_nonce%%, ולהחליף אותו בפרמטר השאילתה של המזהה החד-פעמי שסיפקתם בשלב הקודם. מידע נוסף על האופן שבו מבצעים את הפעולה הזו אמור להיות זמין במסמכי העזרה של שרת המודעות של הצד השלישי.