یک آداپتور سیگنال امن ایجاد کنید، یک آداپتور سیگنال امن ایجاد کنید

پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS

سیگنال‌های امن، داده‌های رمزگذاری‌شده‌ای هستند که یک دستگاه کلاینت جمع‌آوری کرده و با پیشنهاددهندگان منتخب به اشتراک می‌گذارد. این صفحه شما را در جمع‌آوری و ارسال سیگنال‌های امن به Google Ad Manager با استفاده از SDK تبلیغات رسانه‌ای تعاملی (IMA) راهنمایی می‌کند.

قبل از اینکه شروع کنی

قبل از ادامه، مطمئن شوید که IMA SDK برای iOS نسخه ۳.۱۸.۵ یا بالاتر را دارید.

رابط آداپتور سیگنال امن را ایجاد کنید

برای جمع‌آوری و ارائه سیگنال‌های امن، کلاس‌هایی ایجاد کنید که رابط را پیاده‌سازی می‌کنند:

هدف-سی

  • فایل 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

سویفت 

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 هر آداپتور را یک بار با فراخوانی متد initialization آن آداپتور، مقداردهی اولیه می‌کند. این متد را برای شروع هرگونه وابستگی رمزگذاری، تنظیم حافظه‌های پنهان یا پیش‌محاسبه هر سیگنالی که در تمام فراخوانی‌های جمع‌آوری سیگنال ثابت می‌ماند، پیاده‌سازی کنید.

مثال زیر آداپتور را مقداردهی اولیه می‌کند:

هدف-سی 

...
@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;
}
...

سویفت 

...
@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 یک متد جمع‌آوری سیگنال‌ها را به صورت ناهمزمان فراخوانی می‌کند. این متدهای جمع‌آوری سیگنال شامل یک تابع فراخوانی برای ارسال سیگنال‌های رمزگذاری شده یا گزارش خطا هستند.

مثال‌های زیر سیگنال‌های امن را از طریق تابع فراخوانی جمع‌آوری می‌کنند:

هدف-سی 

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

سویفت 

...
  /**
  * 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 نسخه آداپتور شما را در هر درخواست تبلیغ قرار می‌دهد و آنها را با سیگنال‌های امن در یک درخواست پیشنهاد قیمت ارسال می‌کند.

در درخواست پیشنهاد، بر اساس نسخه آداپتور، می‌توانید جزئیات رمزگذاری، کدگذاری و قالب‌بندی مورد استفاده آداپتور برای ایجاد سیگنال‌های امن را شناسایی کنید.

مثال زیر نسخه آداپتور را مشخص می‌کند:

هدف-سی 

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

سویفت 

...
  /**
  * 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 را درخواست و برمی‌گردانند:

هدف-سی 

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

سویفت 

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

آداپتور را در گوگل ثبت کنید

برای اینکه گوگل به آداپتور اجازه جمع‌آوری سیگنال بدهد، باید نام کلاس iOS را در گوگل ثبت کنید. IMA SDK فقط آداپتورهایی را که در گوگل ثبت می‌کنید، مقداردهی اولیه می‌کند.

آداپتور را تأیید کنید

برای تأیید آداپتور، بخش‌های زیر را تکمیل کنید:

پیکربندی برنامه آزمایشی

قبل از اعتبارسنجی آداپتور، برنامه آزمایشی را پیکربندی کنید. مراحل زیر را انجام دهید:

  1. IMA SDK را به پروژه XCode خود اضافه کنید .

  2. آداپتور سیگنال‌های امن خود را به پروژه XCode خود اضافه کنید.

سیگنال‌ها را تأیید کنید

برای تأیید طول سیگنال امن، مقدار رمزگذاری شده، نسخه آداپتور شما؛ و نسخه SDK شما، با پشتیبانی تماس بگیرید تا گزارش ترافیک ضبط شده را به اشتراک بگذارید.

بررسی مثال‌های کامل

این بخش نمونه تکمیل‌شده‌ی تمام مراحل را ثبت کرده و برای مرجع شما در دسترس است.

هدف-سی

  • فایل 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

سویفت 

@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
  }
}