מתחילים

השלב הראשון הוא להוסיף את 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:20.2.0'
    ...
}

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

יצירת צופן חד-פעמי

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

הפונקציה הזו מפעילה יצירה צולבת באופן אסינכרוני, לכן צריך להטמיע 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()

צירוף צופן חד-פעמי לבקשה להצגת מודעה

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

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

/**
 * 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, קראו את הקטע הבא: למסמכי התיעוד של השרת כדי לתעד ולהעביר את הערך צופן חד-פעמי בכל מודעה בקשה. הדוגמה שסופקה היא כתובת URL של בקשה להצגת מודעה עם פרמטר noce כלול. פרמטר ה-noce מופץ מ-PAL SDK דרך בשרתים מתווכים, ולאחר מכן ל-Ad Manager, וכך לאפשר מונטיזציה טובה יותר.

הערה: אם אתם משתמשים בכמה פתרונות של צד שלישי, למשל שרת SSAI של צד שלישי שמפעיל שרת מודעות אחר של צד שלישי, עליכם לוודא שה-nonce המוצפן של PAL SDK מועבר לכל צד שלישי.

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

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

לפרטים נוספים, אפשר לעיין במאמר הטמעה בצד השרת של Google Ad Manager guide.

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