Güvenli sinyal adaptörü oluşturma

Güvenli sinyaller, istemci cihazın topladığı ve 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 Android için IMA SDK'sının 3.29.0 veya daha yeni 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:

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ı 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:

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

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.

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

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

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:

  ...
  /**
   * 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ü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:

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

Google'ın, adaptörü sinyal toplama için yetkilendirmesi amacıyla Android paket adını Google'a kaydetmeniz gerekir. IMA SDK'sı 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 ekleyin. Örneğin: app/build.gradle

    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. İşlem başarılı olursa her reklam isteğinde sinyalleri görürsünüz.

Örnekleri eksiksiz olarak inceleyin

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

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