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

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

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

قبل البدء

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

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

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

ملاحظة: تحمّل حزمة تطوير البرامج للإعلانات التفاعلية فئة المحوّل باستخدام الانعكاس. لمنع إزالة الرمز البرمجي الذي تم تصغيره في مدّة التصميم، أضِف علامة توضيح @Keep من 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) طريقة جمع الإشارات بشكل غير متزامن. تحتوي طرق جمع الإشارات هذه على دالّة رد الاتصال لتمرير الإشارات المشفّرة أو الإبلاغ عن خطأ.

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

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

في سير العمل، تأكَّد من تحديد إصدار المحوّل. تتضمّن حزمة تطوير البرامج للإعلانات التفاعلية (IMA 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. في كل طلب عرض إعلان، تتضمّن حزمة تطوير البرامج للإعلانات التفاعلية (IMA 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. أضِف مصادر الاعتمادية الخاصة بحزمة تطوير البرامج لإعلانات الوسائط التفاعلية إلى ملف 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]);
  }
}