יצירת מתאם אותות מאובטחים

אותות מאובטחים הם נתונים מקודדים שמכשיר לקוח אוסף ומשתף עם מגישי הצעות מחיר נבחרים. בדף הזה מוסבר איך לאסוף ולשלוח אותות מאובטחים אל Google Ad Manager באמצעות Interactive Media Ads (IMA) SDK.

לפני שמתחילים

לפני שממשיכים, צריך לוודא שיש לכם IMA SDK ל-Android בגרסה 3.29.0 ואילך.

יצירת ממשק מתאם לאות מאובטח

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

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
}

אתחול המתאם

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

בדוגמה הבאה מתבצעת אתחול של המתאם:

  ...
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    // Initialize your SDK and any dependencies.
    ...

    // Notify IMA SDK of initialization success.
    callback.onSuccess();

    // If signal collection fails, call callback.onFailure();
    // callback.onFailure(new Exception("Signal collection failed."));
  }
  ...

איסוף אותות

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

בדוגמאות הבאות, האותות המאובטחים נאספים באמצעות פונקציית הקריאה החוזרת:

  ...
  /**
   * Invokes your SDK to collect, encrypt and pass the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {

    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  ...

דיווח על שגיאות

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

אלה השגיאות שעשויות להופיע:

  • לא נמצא SDK או רכיב תלוי באפליקציה.
  • ל-SDK או לרכיב תלוי אין את ההרשאה הנדרשת או את הסכמת המשתמש כדי לפעול.

ציון גרסת המתאם

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

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

בדוגמה הבאה מצוינת גרסת המתאם:

  ...
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  ...
  /**
   * @return The version of this adapter.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  ...

החזרת גרסת זמן הריצה של ה-SDK

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

בדוגמאות הבאות מוצגת בקשה להחזרת גרסת זמן הריצה של ה-SDK:

  ...
  /**
   * @return The version of your SDK that this adapter is depending on.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;

    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
  ...

רישום המתאם ב-Google

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

אימות המתאם

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

הגדרת אפליקציית הבדיקה

לפני שמאמתים את המתאם, צריך להגדיר את אפליקציית הבדיקה. מבצעים את השלבים הבאים:

  1. מוסיפים את יחסי התלות של IMA SDK לקובץ Gradle ברמת האפליקציה של המודול, כמו app/build.gradle:

    dependencies {
  implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0'
}

  2. מוסיפים יחסי תלות של build, כמו המתאם וערכת ה-SDK.

אימות האותות

כדי לוודא שהמתאם שולח אותות, משתמשים ב-proxy של הרשת כדי לעקוב אחרי תנועת הבקשות להצגת מודעות באפליקציה. אם הפעולה תצליח, האותות יופיעו בכל בקשה להצגת מודעה.

עיון בדוגמאות המלאות

בקטע הזה מופיעה דוגמה מלאה של כל השלבים, והיא זמינה לעיונכם.

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.VersionInfo;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsCollectSignalsCallback;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsInitializeCallback;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    try {
      // Initialize your SDK and any dependencies.
      ...

      // Notify IMA SDK of initialization success.
      callback.onSuccess();
    } catch (Exception e) {
      // Pass initialization failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * Invokes your SDK to collect, encrypt and send the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {
    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * @return The version of this adapter.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  /**
   * @return The version of your SDK that this adapter is depending on.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;
    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
}