Güvenli sinyal adaptörü oluşturma

Güvenli sinyaller, bir istemci cihazın topladığı ve belirli teklif verenlerle paylaştığı kodlanmış verilerdir. Bu sayfada, Interactive Media Ads (IMA) SDK'sını kullanarak güvenli sinyalleri Google Ad Manager'a toplama ve gönderme konusunda size yol gösterilir.

Başlamadan önce

Devam etmeden önce Android için IMA SDK'nın 3.29.0 veya daha yeni bir sürümüne sahip olduğunuzu doğrulayın.

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

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

Not: IMA SDK, yansıtma kullanarak bağdaştırıcı sınıfınızı yükler. Derleme sırasında küçültülmüş kodun kaldırılmasını önlemek için sınıfınıza Android ek açıklamasını @Keep ekleyin.

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

Adaptörü başlatma

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ını 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 bağdaştırıcı başlatılıyor:

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

Sinyal toplama

Reklam isteği başlatılmadan önce IMA SDK, sinyal toplama yöntemini eşzamansız olarak çağırır. Bu sinyal toplayıcı yöntemler, şifrelenmiş sinyalleri iletmek veya bir hatayı bildirmek için geri çağırma işlevi içerir.

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

Aşağıdaki örneklerde, geri çağırma işlevi aracılığıyla güvenli sinyaller toplanır:

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

Hata bildirme

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

Görüntülenebilecek hatalar şunlardır:

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

Adaptör sürümünü belirtin

İş akışınızda bağdaştırıcının sürümünü belirttiğinizi doğrulayın. IMA SDK, her reklam isteğine bağdaştırıcı sürümünüzü ekler ve bunları bir teklif isteğindeki güvenli sinyallerle birlikte 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 sinyalleri oluşturmak için kullandığı şifreleme, kodlama ve biçimlendirme ayrıntılarını belirleyebilirsiniz.

Aşağıdaki örnekte bağdaştırıcı sürümü belirtilmektedir:

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

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ışması için SDK'nın çalışma zamanı sürümünü döndürdüğünüzü doğrulayın. IMA SDK, her reklam isteğinde çalışma zamanı sürümünü bağdaştırıcı sürümüyle birlikte içerir.

Aşağıdaki örneklerde SDK çalışma zamanı sürümü isteniyor ve döndürülüyor:

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

Adaptörü Google'a kaydedin

Google'ın bağdaştırıcıyı sinyal toplama için yetkilendirmesi amacıyla Android paket adını veya Google ile 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ına ait bağımlılıkları, modülünüzün uygulama düzeyindeki Gradle dosyasına (ör. app/build.gradle) ekleyin:

   dependencies {
     implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0'
   }
   

2. Bağdaştırıcınız ve SDK'nız gibi derleme bağımlılıkları ekleyin.

Sinyalleri doğrulama

Adaptörünüzün sinyal gönderdiğini doğrulamak için uygulamanızın reklam isteği trafiğini izlemek üzere bir ağ proxy'si kullanın. Başarılı olursa sinyalleri her reklam isteğinde görürsünüz.

Eksiksiz örnekleri inceleyin

Bu bölümde, tüm adımların tamamlanmış örneği yer alır ve referansınız için kullanılabilir.

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]);
  }
}