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

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

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

قبل البدء

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

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

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

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

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

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

يُهيئ المثال التالي المحوّل:

  ...
  /**
   * 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 مللي ثانية، تتجاهل حزمة تطوير البرامج للإعلانات التفاعلية (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);
    }
  }
  ...

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

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

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

• لم يتم العثور على حزمة 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 SDK إلا المحوّلات التي تسجّلها لدى 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]);
  }
}