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

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

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

לפני שממשיכים, צריך לוודא שיש לכם את IMA SDK ל-iOS גרסה 3.18.5 ואילך.

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

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

Objective-C

  • ‫MySecureSignalsAdapter.h:
#import <Foundation/Foundation.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
/** An example implementation of Secure Signals adapter. */
@interface MySecureSignalsAdapter : NSObject <IMASecureSignalsAdapter>
@end
  • ‫MySecureSignalsAdapter.m:
@implementation MySecureSignalsAdapter

  /**
* Default constructor with no arguments for IMA SDK to instantiate this class.
*/
- (instancetype)init {
  self = [super init];

  return self;
}
@end

Swift 

import Foundation
import GoogleInteractiveMediaAds

/** An example implementation of Secure Signals adapter. */
@objc(MySecureSignalsAdapter)
public class MySecureSignalsAdapter: IMASecureSignalsAdapter {
  /**
  * Default constructor with no arguments for IMA SDK to instantiate this class.
  */
  override init() {
    super.init()
  }
}

אתחול המתאם

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

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

Objective-C 

...
@interface MySecureSignalsAdapter
@property(nonatomic) NSError *initError;
@end
...
/**
* Initialize your SDK and any dependencies.
* IMA SDK calls this function exactly once before signal collection.
*/
- (instancetype)init {
  self = [super init];
  @try {
    // Initialize your SDK and any dependencies.
    ...
  }
  @catch(NSException *exception) {
    // Build NSError to be passed by Signal Collector.
    _initError = ...;
  }
  return self;
}
...

Swift 

...
@objc(MySecureSignalsAdapter)
public class MySecureSignalsAdapter: IMASecureSignalsAdapter {
...
  private var initError

  override init() {
    super.init()

    do {
      // Initialize your SDK and any dependencies.
      ...
    } catch {
      // Build NSError to be passed by Signal Collector.
      self.initError = ...;
    }
  }
}

איסוף אותות

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

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

Objective-C 

...
/**
* 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 completion A callback function to pass signal collection results to IMA SDK.
*/
- (void)collectSignalsWithCompletion:(IMASignalCompletionHandler)completion {
  // Output any initialization errors
  if (self.initError) {
    completion(nil, self.initError);
    return;
  }
  @try {
    // Collect and encrypt the signals.
    NSString *signals = ...
    // Pass the encrypted signals to IMA SDK.
    completion(signals, nil);
  }
  @catch(NSException *exception) {
    NSError *collectSignalError = ...;
    // Pass signal collection failures to IMA SDK.
    completion(nil, collectSignalError);
  }
}
...

Swift 

...
  /**
  * 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 completion A callback function to pass signal collection results to IMA SDK.
  */
  public func collectSignals(completion: @escaping IMASignalCompletionHandler) {
    if (self.initError) {
      completion(nil, self.initError)
      return
    }

    do {
      // Collect and encrypt the signals.
      var signals = ...
      // Pass the encrypted signals to IMA SDK.
      completion(signals, nil)
    } catch {
      NSError collectSignalError = ...
      // Pass signal collection failures to IMA SDK.
      completion(nil, collectSignalError)
    }
  }
...

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

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

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

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

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

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

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

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

Objective-C 

...
/**
* Specifies this adapter's version.
*/
static NSInteger const VersionMajor = 1;
static NSInteger const VersionMinor = 0;
static NSInteger const VersionPatch = 1;
...
/**
* @return The version of this adapter.
*         IMA SDK calls this function before each ad request.
*/
+ (IMAVersion *)adapterVersion {
  // The version of the SecureSignals Adapter.
  IMAVersion *adapterVersion = [[IMAVersion alloc] init];
  adapterVersion.majorVersion = VersionMajor;
  adapterVersion.minorVersion = VersionMinor;
  adapterVersion.patchVersion = VersionPatch;
  return adapterVersion;
}
...

Swift 

...
  /**
  * Specifies this adapter's version.
  */
  static let VersionMajor = 1;
  static let VersionMinor = 0;
  static let VersionPatch = 1;
...
  /**
  * @return The version of this adapter.
  *         IMA SDK calls this function before each ad request.
  */
  public static func adapterVersion() -> IMAVersion {
    let adapterVersion = IMAVersion()
    adapterVersion.majorVersion = self.VersionMajor
    adapterVersion.minorVersion = self.VersionMinor
    adapterVersion.patchVersion = self.VersionPatch
    return adapterVersion
  }
...

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

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

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

Objective-C 

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

  IMAVersion *adSDKVersion = [[IMAVersion alloc] init];
  adSDKVersion.majorVersion = mySDKVersion[0];
  adSDKVersion.minorVersion = mySDKVersion[1];
  adSDKVersion.patchVersion = mySDKVersion[2];

  return adSDKVersion;
}
...

Swift 

...
  /**
  * @return The version of your SDK that this adapter is depending on.
  *         IMA SDK calls this function before each ad request.
  */
public static func adSDKVersion() -> IMAVersion {
    // Request the version from your SDK and convert to an IMAVersion.
    let mySDKVersion = ...

    let adSDKVersion = IMAVersion()
    adSDKVersion.majorVersion = mySDKVersion[0]
    adSDKVersion.minorVersion = mySDKVersion[1]
    adSDKVersion.patchVersion = mySDKVersion[2]
    return adSDKVersion
  }
...

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

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

אימות המתאם

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

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

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

  1. מוסיפים את IMA SDK לקובץ ה-Pod:

    source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.17.0'
end

  2. מתקינים את IMA SDK באמצעות CocoaPods. הוראות להתקנת IMA SDK דרך CocoaPods מופיעות במאמר תחילת העבודה.

  3. בפרויקט XCode, מוסיפים את המתאם, ה-SDK וכל יתר התלות ב-build שהוספתם.

אימות האותות

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

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

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

Objective-C

  • ‫MySecureSignalsAdapter.h:
#import <Foundation/Foundation.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

/** An example implementation of Secure Signals adapter. */
@interface MySecureSignalsAdapter : NSObject <IMASecureSignalsAdapter>
@end
  • ‫MySecureSignalsAdapter.m:
#import "path/to/MyExampleSecureSignalsAdapter.h"

@interface MySecureSignalsAdapter
@property(nonatomic) NSError *initError;
@end

static NSInteger const VersionMajor = 1;
static NSInteger const VersionMinor = 0;
static NSInteger const VersionPatch = 1;

@implementation MySecureSignalsAdapter
/**
* Initialize your SDK and any dependencies.
* IMA SDK calls this function exactly once before signal collection.
*/
- (instancetype)init {
  self = [super init];
  @try {
    // Initialize your SDK and any dependencies.
    ...
  }
  @catch(NSException *exception) {
    // Build NSError to be passed by Signal Collector.
    _initError = ...;
  }
  return self;
}
/**
* 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 completion A callback function to pass signal collection results to IMA SDK.
*/
- (void)collectSignalsWithCompletion:(IMASignalCompletionHandler)completion {
  if (self.initError) {
    completion(nil, self.initError);
    return;
  }
  @try {
    // Collect and encrypt the signals.
    NSString *signals = ...
    // Pass the encrypted signals to IMA SDK.
    completion(signals, nil);
  }
  @catch(NSException *exception) {
    NSError *collectSignalError = ...;
    // Pass signal collection failures to IMA SDK.
    completion(nil, collectSignalError);
  }
}
/**
* @return The version of this adapter.
*         IMA SDK calls this function before each ad request.
*/
+ (IMAVersion *)adapterVersion {
  // The version of the SecureSignals Adapter.
  IMAVersion *adapterVersion = [[IMAVersion alloc] init];
  adapterVersion.majorVersion = VersionMajor;
  adapterVersion.minorVersion = VersionMinor;
  adapterVersion.patchVersion = VersionPatch;
  return adapterVersion;
}

/**
  * @return The version of your SDK that this adapter depends on.
  *         IMA SDK calls this function before each ad request.
  */
+ (IMAVersion *)adSDKVersion {
  // Request the version from your SDK and convert to an IMAVersion.
  int mySDKVersion[3] = ...

  IMAVersion *adSDKVersion = [[IMAVersion alloc] init];
  adSDKVersion.majorVersion = mySDKVersion[0];
  adSDKVersion.minorVersion = mySDKVersion[1];
  adSDKVersion.patchVersion = mySDKVersion[2];

  return adSDKVersion;
}

@end

Swift 

@objc(MySecureSignalsAdapter)
public class MySecureSignalsAdapter: IMASecureSignalsAdapter {
  static let VersionMajor = 1;
  static let VersionMinor = 0;
  static let VersionPatch = 1;

  private var initError

  override init() {
    super.init()

    do {
      // Initialize your SDK and any dependencies.
      ...
    } catch {
      // Build NSError to be passed by Signal Collector.
      self.initError = ...;
    }
  }

  public func collectSignals(completion: @escaping IMASignalCompletionHandler) {
    if (self.initError) {
      completion(nil, self.initError)
      return
    }

    do {
      // Collect and encrypt the signals.
      var signals = ...
      // Pass the encrypted signals to IMA SDK.
      completion(signals, nil)
    } catch {
      NSError collectSignalError = ...
      // Pass signal collection failures to IMA SDK.
      completion(nil, collectSignalError)
    }      
  }

  public static func adapterVersion() -> IMAVersion {
    let adapterVersion = IMAVersion()
    adapterVersion.majorVersion = self.VersionMajor
    adapterVersion.minorVersion = self.VersionMinor
    adapterVersion.patchVersion = self.VersionPatch
    return adapterVersion
  }

  public static func adSDKVersion() -> IMAVersion {
    // Request the version from your SDK and convert to an IMAVersion.
    let mySDKVersion = ...

    let adSDKVersion = IMAVersion()
    adSDKVersion.majorVersion = mySDKVersion[0]
    adSDKVersion.minorVersion = mySDKVersion[1]
    adSDKVersion.patchVersion = mySDKVersion[2]
    return adSDKVersion
  }
}