الخطوات الأولى

تتمثل الخطوة الأولى في إضافة حزمة تطوير البرامج (SDK) لنظام التشغيل PAL لنظام التشغيل Android إلى تطبيقك.

إضافة حزمة تطوير البرامج (SDK) لمنصة Android PAL كمكتبة

اعتبارًا من الإصدار 18.0.0، تتم استضافة حزمة تطوير البرامج (SDK) لمنصة PAL في مستودع Maven من Google، ويمكن إضافتها إلى تطبيقك على النحو التالي:

app/build.gradle

...
dependencies {
    implementation 'com.google.android.gms:play-services-pal:20.2.0'
    ...
}

بدلاً من ذلك، يمكن تنزيل حزمة PAL SDK من مستودع Maven التابع لشركة Google وإضافتها يدويًا إلى تطبيقك.

إنشاء nonce

"المفتاح المؤقت" هو سلسلة مشفّرة واحدة يتم إنشاؤها بواسطة PAL باستخدام NonceLoader. تتطلّب حزمة PAL SDK أن يقترن كل طلب بث جديد بحزمة تم إنشاء nonce. ومع ذلك، يمكن إعادة استخدام nonces لطلبات الإعلان المتعددة ضمن البث نفسه. لإنشاء رقم هاتف واحد باستخدام حزمة تطوير البرامج (SDK) لنظام التشغيل PAL، يجب إجراء تغييرات على MyActivity.java للاطلاع على نموذج تطبيق يستخدم PAL لإنشاء رقم غير صحيح، قم بتنزيل مثال Android من GitHub.

يجب أولاً استيراد حزمة تطوير البرامج (SDK) الخاصة بنظام PAL، وإنشاء بعض المواقع الخاصة لتخزينها. NonceLoader وNonceManager، ثم إعداد NonceLoader.

ننصحك بإنشاء مثيل واحد فقط للفئة NonceLoader من أجل كل جلسة مستخدم في تطبيقك ما لم يتضمّن التطبيق صفحات متعددة أو ما يعادلها التركيبات. يؤدي هذا إلى الحفاظ على ارتباط الصفحة (&correlator) دون تغيير بالنسبة إلى الفترة منذ إنشاء الصفحة أو جلسة المستخدم على التطبيق. لا يزال بإمكانك التحكم في أداة ربط البث (&scor) التي من المفترض أن تتم إعادة ضبطها مرة واحدة لكل مصدر بيانات جديد.

يجب أن تتشارك جميع طلبات الإعلانات للبث نفسه بيانات NonceLoader ونفسها قيمة ارتباط البث لتحديد عدد مرات الظهور والاستبعاد التنافسي بشكل صحيح.

import android.app.Activity;
import android.os.Bundle;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;

import java.util.HashSet;
import java.util.Set;

public class MainActivity extends Activity {
...
  private NonceLoader nonceLoader;
  private NonceManager nonceManager = null;
  private ConsentSettings consentSettings;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // The default value for allowStorage() is false, but can be
    // changed once the appropriate consent has been gathered. The
    // getConsentToStorage() method is a placeholder for the publisher's own
    // method of obtaining user consent, either by integrating with a CMP or
    // based on other methods the publisher chooses to handle storage consent.

    boolean isConsentToStorage = getConsentToStorage();

    videoView = findViewById(R.id.video_view);
    videoView.setOnTouchListener(this::onVideoViewTouch);

    consentSettings = ConsentSettings.builder()
            .allowStorage(isConsentToStorage)
            .build();

    // It is important to instantiate the NonceLoader as early as possible to
    // allow it to initialize and preload data for a faster experience when
    // loading the NonceManager. A new NonceLoader will need to be instantiated
    //if the ConsentSettings change for the user.
    nonceLoader = new NonceLoader(this, consentSettings);
    ...
  }

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

تؤدي هذه الدالة إلى إنشاء غير متزامن، لذا تحتاج إلى تنفيذ AsyncTask للتعامل مع نجاح أو تعذُّر الطلب:

public void generateNonceForAdRequest() {
  Set supportedApiFrameWorksSet = new HashSet();
  // The values 2, 7, and 9 correspond to player support for VPAID 2.0,
  // OMID 1.0, and SIMID 1.1.
  supportedApiFrameWorksSet.add(2);
  supportedApiFrameWorksSet.add(7);
  supportedApiFrameWorksSet.add(9);

  NonceRequest nonceRequest = NonceRequest.builder()
      .descriptionURL("https://example.com/content1")
      .iconsSupported(true)
      .omidPartnerVersion("6.2.1")
      .omidPartnerName("Example Publisher")
      .playerType("ExamplePlayerType")
      .playerVersion("1.0.0")
      .ppid("testPpid")
      .sessionId("Sample SID")
      .supportedApiFrameworks(supportedApiFrameWorksSet)
      .videoPlayerHeight(480)
      .videoPlayerWidth(640)
      .willAdAutoPlay(true)
      .willAdPlayMuted(false)
      .build();
  NonceCallbackImpl callback = new NonceCallbackImpl();
  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(callback)
      .addOnFailureListener(callback);
}

private class NonceCallbackImpl implements OnSuccessListener<NonceManager>, OnFailureListener {
  @Override
  public void onSuccess(NonceManager manager) {
    nonceManager = manager;
    String nonceString = manager.getNonce();
    Log.i("PALSample", "Generated nonce: " + nonceString);
    // from here you would trigger your ad request and move on to initialize content
  }

  @Override
  public void onFailure(Exception error) {
    Log.e("PALSample", "Nonce generation failed: " + error.getMessage());
  }
}

بعد إنشاء حساب إداري خاص، يمكن استرداد الرقم في أي وقت باستخدام nonceManager.getNonce()

إرفاق مفتاح عشوائي بطلب الإعلان

لاستخدام القيمة التي تم إنشاؤها، أضِف علامة الإعلان بمَعلمة givn قيمة خاصة قبل إنشاء طلبات الإعلان.

تنبيه: إذا سبق أن قدّمت رقم غير خاص باستخدام المعلمة paln، يجب مراعاة ما يلي: نوصي بشدة بالتحويل إلى givn وإيقاف إرسال paln. إذا كان كلاهما التي يتم تضمينها، فهي سلوك غير محدد بخصوص أي معلمة غير محددة مستعمَل.

/**
 * The ad tag for your ad request, for example:
 * https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external\
 * /single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1\
 * &cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=
 *
 * For more sample ad tags, see
 * developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
 */
private static final String DEFAULT_AD_TAG = "Your ad tag";
...
@Override
public void onSuccess(NonceManager manager) {
  nonceManager = manager;
  String nonceString = manager.getNonce();
  Log.i("PALSample", "Generated nonce: " + nonceString);
  // Append the nonce to the ad tag URL.
  makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
}

تتبُّع أحداث التشغيل

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

public void sendAdClick() {
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

public void sendPlaybackStart() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

public void sendPlaybackEnd() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendTouch(e);
  }
}

إليك متى يجب استدعاء كل دالة في التنفيذ:

• sendPlaybackStart(): عند بدء جلسة تشغيل الفيديو
• sendPlaybackEnd(): عند انتهاء جلسة تشغيل الفيديو
• sendAdClick(): في كل مرة ينقر فيها المشاهد على إعلان
• sendTouch(): عند كل تفاعل باللمس مع اللاعب

(اختياري) إرسال إشارات "مدير إعلانات Google" من خلال خوادم الإعلانات التابعة لجهات خارجية

عند إعداد خادم إعلانات تابع لجهة خارجية للعمل مع "مدير إعلانات Google"، يمكنك الرجوع إلى إلى مستندات الخادم لتسجيل وإعادة توجيه القيمة التي تخصّ القيمة في كل إعلان طلبك. المثال المقدَّم هو عنوان URL لطلب إعلان يتضمّن المَعلمة nonce . يتم نشر المعلمة nonce من PAL SDK من خلال خوادم وسيطة، ثم إلى "مدير إعلانات Google"، ما يعزّز تحقيق الربح لديها.

ملاحظة: في حال استخدام حلول متعدّدة تابعة لجهات خارجية، مثل حلول تابعة لجهات خارجية يتصل خادم SSAI بخادم إعلانات تابع لجهة خارجية آخر، وعليك التأكد من أن قائمة PAL تتم إعادة توجيه الملف الخاص بحزمة تطوير البرامج (SDK) المشفَّرة إلى كل جهة خارجية.

عليك ضبط خادم الإعلانات التابع لجهة خارجية لتضمين المفتاح العشوائي في طلب الخادم إلى "مدير إعلانات Google". في ما يلي مثال على علامة إعلان تم ضبطها داخل خادم إعلانات الجهة الخارجية:

'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'

لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة التنفيذ من جهة الخادم في "مدير إعلانات Google". الدليل.

يبحث "مدير إعلانات Google" عن givn= لتحديد قيمة nonce. إعلان الجهة الخارجية خادم إلى دعم بعض وحدات الماكرو الخاصة به، مثل %%custom_key_for_google_nonce%%، واستبداله بمَعلمة طلب البحث nonce التي قدمتها في الخطوة السابقة. مزيد من المعلومات حول كيفية تحقيق ذلك يجب أن يكون متاحًا في مستندات خادم إعلانات الجهة الخارجية.