התחל בעבודה

‫PAL מאפשרת לכם לשלוח אותות של מודעות Google בבקשות להצגת מודעות ובמהלך הפעלת המודעות.

במדריך הזה מוסבר איך להוסיף את Android PAL SDK לאפליקציה. כדי לראות אפליקציה לדוגמה שמשתמשת ב-PAL כדי ליצור מספר חד-פעמי, אפשר להוריד את הדוגמה ל-Android מ-GitHub.

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

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

implementation 'com.google.android.gms:play-services-pal:22.1.0'
build.gradle

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

יצירת מספר חד-פעמי

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

  1. כדי לייבא ולהגדיר את PAL:

    1. ייבוא כיתות PAL:

      import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;
import java.util.HashSet;
import java.util.Set;

      MainActivity.java

    2. יוצרים משתנים פרטיים לאחסון המופעים של NonceLoader ושל NonceManager:

      private NonceLoader nonceLoader;
private NonceManager nonceManager;
      MainActivity.java

    3. מאתחלים את מופע NonceLoader באמצעות מופע ConsentSettings בשיטה onCreate:

      @Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  // 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 isStorageAllowed = getConsentToStorage();

  ConsentSettings consentSettings =
      ConsentSettings.builder().allowStorage(isStorageAllowed).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);

  adClickButton = findViewById(R.id.send_click_button);

  logView = findViewById(R.id.log_view);
  logView.setMovementMethod(new ScrollingMovementMethod());
}

      MainActivity.java

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

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

  2. יצירת מספר חד-פעמי:

    public void generateNonceForAdRequest(View view) {
  logMessage("Generate Nonce Request");
  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();

  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(
          new OnSuccessListener<NonceManager>() {
            @Override
            public void onSuccess(NonceManager manager) {
              nonceManager = manager;
              String nonceString = manager.getNonce();
              logMessage("Nonce generated");
              logMessage(nonceString.substring(0, 20) + "...");
              Log.i(LOG_TAG, "Generated nonce: " + nonceString);

              // From here you would trigger your ad request and move on to initialize content.
              exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);

              adClickButton.setEnabled(true);
            }
          })
      .addOnFailureListener(
          new OnFailureListener() {
            @Override
            public void onFailure(Exception error) {
              logMessage("Nonce generation failed");
              Log.e(LOG_TAG, "Nonce generation failed: " + error.getMessage());
            }
          });
}

    MainActivity.java

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

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

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

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

// From here you would trigger your ad request and move on to initialize content.
exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
MainActivity.java

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

כדי לעקוב אחרי אירועי הפעלה, צריך להגדיר את הפונקציות לטיפול באירועים כך שישלחו אותות מודעות אל Google:

// Triggered when a user clicks-through on an ad which was requested using a PAL nonce.
public void sendAdClick(View view) {
  logMessage("Ad click sent");
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

// In a typical PAL app, this is called when a user touch or click is detected,
// on the ad other than an ad click-through.
public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendAdTouch(e);
  }
}

// In a typical PAL app, this is called when a content playback session starts.
public void sendPlaybackStart() {
  logMessage("Playback start");
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

// In a typical PAL app, this is called when a content playback session ends.
public void sendPlaybackEnd() {
  logMessage("Playback end");
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

MainActivity.java

בהמשך מפורט מתי צריך להפעיל כל פונקציה בהטמעה:

  • ‫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%%, ולהחליף אותו בפרמטר השאילתה של ה-nonce שסיפקתם בשלב הקודם. מידע נוסף על האופן שבו אפשר לעשות זאת זמין במסמכי התיעוד של שרת המודעות של הצד השלישי.