ایجاد آداپتور سیگنال‌های ایمن

پلاتفرم را انتخاب کنید: Android iOS

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

قبل‌از شروع

قبل‌از ادامه دادن، مطمئن شوید که کیت توسعه نرم‌افزار IMA برای 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

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()
  }
}

مقداردهی اولیه آداپتور

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

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

آبجکتیو-سی 

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

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

آبجکتیو-سی 

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

گزارش کردن خطاها

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

خطاهایی که ممکن است ظاهر شوند به شرح زیر است:

  • کیت توسعه نرم‌افزار یا وابستگی شما در برنامه پیدا نشد.
  • کیت توسعه نرم‌افزار شما یا وابستگی آن، اجازه یا رضایت کاربر لازم را برای کار کردن ندارد.

نسخه آداپتور را مشخص کنید

در گردش کارتان، مطمئن شوید که نسخه آداپتور را مشخص کرده‌اید. کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی نسخه آداپتور شما را در هر درخواست آگهی لحاظ می‌کند و آن‌ها را با سیگنال‌های امن در درخواست پیشنهاد قیمت ارسال می‌کند.

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

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

آبجکتیو-سی 

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

برگرداندن نسخه زمان اجرای کیت توسعه نرم‌افزار

می‌توانید آداپتور خود را طوری طراحی کنید که با چندین نسخه از کیت توسعه نرم‌افزار شما کار کند. برای اینکه آداپتور با چندین نسخه کار کند، مطمئن شوید که نسخه زمان اجرای کیت توسعه نرم‌افزار را برمی‌گردانید. در هر درخواست آگهی، IMA 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;
}
...

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 فقط آداپتورهایی را مقداردهی اولیه می‌کند که در Google ثبت کرده باشید.

اعتبارسنجی آداپتور

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

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

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

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

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

درستی‌سنجی کردن نشان‌ها

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

نمونه‌های کامل را مرور کنید

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

آبجکتیو-سی

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