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

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

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

  ...
  /**
   * 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);
    }
  }
  ...

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

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

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

  • ערכת ה-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]);
  }
}