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

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

قبل البدء

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

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

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

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

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

جمع الإشارات

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

ملاحظة: في غضون 500 ملي ثانية، يجب إكمال عملية جمع الإشارات وتشفيرها وتمرير الإشارة المشفّرة إلى دالة رد الاتصال. بعد 500 مللي ثانية، تتجاهل حزمة تطوير البرامج للإعلانات التفاعلية أي عملية جمع للإشارات.

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

  ...
  /**
   * 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 أو إحدى التبعيات الإذن أو موافقة المستخدم المطلوبَين للعمل.

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

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

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

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

  ...
  /**
   * 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 وتعرضه:

  ...
  /**
   * @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. أضِف عناصر الاعتمادية الخاصة بالإصدار، مثل المحوّل وحزمة 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]);
  }
}