إنشاء محوِّل إشارات آمنة

اختيار النظام الأساسي: Android iOS

الإشارات الآمنة هي بيانات مشفّرة يجمعها جهاز العميل ويشاركها مع مقدّمي عروض أسعار محدّدين. توضّح لك هذه الصفحة كيفية جمع الإشارات الآمنة وإرسالها إلى Google Ad Manager باستخدام حزمة تطوير البرامج (SDK) للإعلانات التفاعلية (IMA).

قبل البدء

قبل المتابعة، تأكَّد من توفّر حزمة تطوير البرامج (SDK) للإعلانات التفاعلية (IMA) لنظام Android الإصدار 3.29.0 أو إصدار أحدث.

إنشاء واجهة محوّل الإشارات الآمنة

لجمع الإشارات الآمنة وتقديمها، أنشئ فئات تنفّذ الواجهة:

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

إعداد المحوّل

تُعدّ حزمة تطوير البرامج (SDK) للإعلانات التفاعلية (IMA) كل محوّل مرة واحدة عن طريق استدعاء طريقة الإعداد الخاصة بالمحوّل. نفِّذ هذه الطريقة لبدء أي تبعيات تشفير أو إعداد ذاكرات تخزين مؤقت أو إجراء أي عمليات حساب مسبق لأي إشارات تظل كما هي في جميع طلبات جمع الإشارات.

يوضّح المثال التالي كيفية إعداد المحوّل:

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

جمع الإشارات

قبل بدء طلب عرض الإعلان، تستدعي حزمة تطوير البرامج (SDK) للإعلانات التفاعلية (IMA) طريقة جمع الإشارات بشكل غير متزامن. تحتوي طرق جمع الإشارات هذه على دالّة رد الاتصال لتمرير الإشارات المشفّرة أو الإبلاغ عن خطأ.

تجمع الأمثلة التالية الإشارات الآمنة من خلال دالة معاودة الاتصال:

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

الإبلاغ عن الأخطاء

للتواصل مع المستخدمين الذين يستخدِمون فئة المحوّل، عليك الإبلاغ عن جميع الأخطاء أثناء جمع الإشارات وتمريرها إلى دالة معاودة الاتصال الخاصة بجمع الإشارات. تساعد هذه العملية في تحديد المشاكل التي تحدث أثناء دمج المحوّل في التطبيقات وحلّها.

في ما يلي الأخطاء التي قد تظهر:

  • لم يتم العثور على حزمة تطوير البرامج (SDK) أو إحدى التبعيات في التطبيق.
  • لا تملك حزمة تطوير البرامج (SDK) أو إحدى التبعيات الإذن المطلوب أو موافقة المستخدم للعمل.

تحديد إصدار المحوّل

في سير العمل، تأكَّد من تحديد إصدار المحوّل. تضمِّن حزمة تطوير البرامج (SDK) للإعلانات التفاعلية (IMA) إصدار المحوّل في كل طلب عرض إعلان وتمرِّرها مع الإشارات الآمنة في طلب عرض السعر.

في طلب عرض السعر، يمكنك تحديد تفاصيل التشفير والترميز والتنسيق التي يستخدمها المحوّل لإنشاء الإشارات الآمنة، وذلك استنادًا إلى إصدار المحوّل.

يوضّح المثال التالي كيفية تحديد إصدار المحوّل:

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

يمكنك تصميم المحوّل ليعمل مع إصدارات متعدّدة من حزمة تطوير البرامج (SDK). لكي يعمل المحوّل مع إصدارات متعدّدة، تأكَّد من عرض إصدار وقت تشغيل حزمة تطوير البرامج (SDK). في كل طلب إعلان، تضمِّن حزمة تطوير البرامج (SDK) للإعلانات التفاعلية (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. لا تُعدّ حزمة تطوير البرامج (SDK) للإعلانات التفاعلية (IMA) سوى المحوّلات التي تسجّلها لدى Google.

التحقّق من المحوّل

للتحقّق من المحوّل، أكمل الأقسام التالية:

إعداد تطبيق الاختبار

قبل التحقّق من المحوّل، عليك إعداد تطبيق الاختبار. أكمِل الخطوات التالية:

  1. أضِف تبعيات حزمة تطوير البرامج (SDK) للإعلانات التفاعلية (IMA) إلى ملف Gradle على مستوى التطبيق في وحدتك، مثل app/build.gradle:

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

  2. أضِف تبعيات الإنشاء، مثل المحوّل وحزمة تطوير البرامج (SDK).

التحقّق من الإشارات

للتحقّق من أنّ المحوّل يرسل الإشارات، استخدِم وكيل شبكة لمراقبة عدد الزيارات لطلبات الإعلانات في تطبيقك. إذا نجحت العملية، ستظهر لك الإشارات في كل طلب عرض إعلان.

مراجعة الأمثلة الكاملة

يحتوي هذا القسم على المثال الكامل لجميع الخطوات، ويمكنك الرجوع إليه.

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