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

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

قبل البدء

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

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

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

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

تهيئة المحوّل

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

يؤدي المثال التالي إلى تهيئة المحوّل:

  ...
  /**
   * 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) لإعلانات الوسائط التفاعلية أسلوب جمع الإشارات بشكل غير متزامن. وتتضمّن طرق تجميع الإشارات هذه وظيفة استدعاء لتمرير الإشارات المشفرة أو الإبلاغ عن خطأ.

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

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