Güvenli sinyal adaptörü oluşturma

Önemli: Güvenli sinyaller beta sürümündedir. Bu belge yalnızca belirli iş ortakları için hazırlanmıştır. Bu dokümanı Google'ın izni olmadan dağıtmayın.

Güvenli sinyaller, bir istemci cihazının toplayıp belirli teklif verenlerle paylaştığı kodlanmış verilerdir. Bu sayfada, Interactive Media Ads (IMA) SDK'sını kullanarak güvenli sinyaller toplama ve Google Ad Manager'a gönderme hakkında bilgi verilmektedir.

Başlamadan önce

Devam etmeden önce iOS için IMA SDK'nın v3.18.5 veya sonraki bir sürümüne sahip olduğunuzdan emin olun.

Güvenli sinyal adaptörü arayüzünü oluşturma

Güvenli sinyaller toplamak ve sağlamak için arayüzü uygulayan sınıflar oluşturun:

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

Bağdaştırıcıyı başlatın

IMA SDK, bağdaştırıcının başlatma yöntemini çağırarak her bağdaştırıcıyı bir kez başlatır. Şifreleme bağımlılıkları başlatmak, önbellekleri ayarlamak veya tüm sinyal toplama çağrılarında aynı kalan sinyalleri önceden hesaplamak için bu yöntemi uygulayın.

Aşağıdaki örnekte adaptör başlatılmaktadır:

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

Sinyal toplama

IMA SDK'sı, bir reklam isteği başlatılmadan önce sinyal toplama yöntemini asenkron olarak çağırır. Bu sinyal toplayıcı yöntemleri, şifrelenmiş sinyalleri iletmek veya bir hatayı bildirmek için bir geri çağırma işlevi içerir.

Not: 500 milisaniye içinde sinyal toplama ve şifreleme işlemlerini tamamlamanız ve şifrelenmiş sinyali geri çağırma işlevine iletmeniz gerekir. IMA SDK'sı, 500 milisaniye sonra tüm sinyal koleksiyonlarını atar.

Aşağıdaki örnekler, güvenli sinyalleri geri çağırma işlevi aracılığıyla toplar:

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

Hataları bildirme

Adaptör sınıfınızı kullanan kullanıcılarla iletişim kurmak için sinyal toplama sırasındaki tüm hataları bildirin ve sinyal toplayıcı geri çağırma işlevine iletin. Bu işlem, adaptörünüzün uygulamalarla entegrasyonu sırasında ortaya çıkan sorunları giderir.

Görünebilecek hatalar şunlardır:

• SDK'nız veya bir bağımlılığınız uygulamada bulunamadı.
• SDK'nız veya bir bağımlılığınız çalışmak için gerekli izne veya kullanıcı iznine sahip değil.

Bağdaştırıcı sürümünü belirtin

İş akışınızda adaptörün sürümünü belirttiğinizden emin olun. IMA SDK'sı, her reklam isteğine bağdaştırıcı sürümünüzü ekler ve bunları bir teklif isteğinde güvenli sinyallerle iletir.

Teklif isteğinde, bağdaştırıcı sürümüne bağlı olarak bağdaştırıcının güvenli sinyaller oluşturmak için kullandığı şifreleme, kodlama ve biçimlendirme ayrıntılarını tanımlayabilirsiniz.

Aşağıdaki örnekte adaptör sürümü belirtilmektedir:

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 çalışma zamanı sürümünü döndürme

Adaptörünüzü SDK'nızın birden fazla sürümüyle çalışacak şekilde tasarlayabilirsiniz. Adaptörün birden fazla sürümle çalışabilmesi için SDK'nın çalışma zamanı sürümünü döndürdüğünüzden emin olun. IMA SDK'sı her reklam isteğinde, uyumlu sürümle birlikte çalışma zamanı sürümünü içerir.

Aşağıdaki örnekler, SDK çalışma zamanı sürümünü ister ve döndürür:

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

Adaptörü Google'a kaydetme

Google'ın, adaptörü sinyal toplama için yetkilendirmesi amacıyla iOS sınıf adını Google'a kaydetmeniz gerekir. IMA SDK yalnızca Google'a kaydettiğiniz bağdaştırıcıları başlatır.

Adaptörü doğrulama

Adaptörü doğrulamak için aşağıdaki bölümleri tamamlayın:

Test uygulamasını yapılandırma

Adaptörü doğrulamadan önce test uygulamasını yapılandırın. Aşağıdaki adımları tamamlayın:

1. IMA SDK'sını pod dosyanıza ekleyin:

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

2. CocoaPods kullanarak IMA SDK'yı yükleyin. IMA SDK'yı CocoaPods aracılığıyla yükleme talimatları için Başlayın bölümüne bakın.

3. XCode projenize bağdaştırıcınızı, SDK'nızı ve eklediğiniz diğer tüm derleme bağımlılıkları ekleyin.

Sinyalleri doğrulama

Güvenli sinyalin uzunluğunu, şifrelenmiş değeri, bağdaştırıcı sürümünüzü ve SDK sürümünüzü doğrulamak için yakalanan trafik günlüğünü paylaşmak üzere destek ekibiyle iletişime geçin.

Örnekleri eksiksiz olarak inceleyin

Bu bölümde, tüm adımların tamamlanmış örneği yer alır ve referans olarak kullanabilirsiniz.

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