אותות מאובטחים הם נתונים מקודדים שמכשיר הלקוח אוסף ומשתף עם מגישי הצעות מחיר נבחרים. בדף הזה מוסבר איך לאסוף אותות מאובטחים ולשלוח אותם אל 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) כדי להעביר את האותות המוצפנים או לדווח על שגיאה.
בדוגמאות הבאות, האותות המאובטחים נאספים באמצעות פונקציית הקריאה החוזרת (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 תאשר את המתאם לאיסוף אותות, צריך לרשום ב-Google את שם החבילה ב-Android או את שם החבילה ב-iOS. ערכת ה-IMA SDK מפעילה רק את המתאמים שרשמתם ב-Google.
אימות המתאם
כדי לאמת את המתאם, מבצעים את הפעולות הבאות:
הגדרת אפליקציית הבדיקה
לפני שמאמתים את המתאם, צריך להגדיר את אפליקציית הבדיקה. כך עושים את זה:
מוסיפים את יחסי התלות של IMA SDK לקובץ Gradle ברמת האפליקציה של המודול, למשל
app/build.gradle:dependencies { implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0' }מוסיפים יחסי תלות של גרסאות 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]);
}
}