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

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

הדוגמה הבאה מפעילה את המתאם:

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

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

בדוגמאות הבאות מבקשים את גרסת סביבת זמן הריצה של ה-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]);
  }
}