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

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

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

قبل‌از شروع

قبل‌از ادامه، مطمئن شوید که «کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی» برای Android نسخه ۳.۲۹.۰ یا بالاتر را دارید.

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

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

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

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

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

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

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

جمع‌آوری سیگنال

قبل‌از شروع درخواست آگهی، 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 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);
    }
  }
  ...

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

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

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

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

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

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

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

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

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

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

می‌توانید آداپتور خود را طوری طراحی کنید که با چندین نسخه از کیت توسعه نرم‌افزار شما کار کند. برای اینکه آداپتور با چندین نسخه کار کند، مطمئن شوید که نسخه زمان اجرای کیت توسعه نرم‌افزار را برمی‌گردانید. در هر درخواست آگهی، IMA SDK نسخه زمان اجرا را با نسخه آداپتور اضافه می‌کند.

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

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

ثبت کردن آداپتور در Google

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

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

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

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

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

  1. وابستگی‌های IMA SDK را به فایل Gradle سطح برنامه واحدتان اضافه کنید، مثلاً app/build.gradle:

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

  2. افزودن وابستگی‌های ساخت مانند آداپتور و کیت توسعه نرم‌افزار.

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

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

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

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

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