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

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

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

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

app/build.gradle

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

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

إنشاء مفتاح عشوائي

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

عليك أولاً استيراد حزمة PAL SDK، وإنشاء بعض المواقع الخاصة لتخزين 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 التي تم ضبطها هنا هي أمثلة على المَعلمات. يجب ضبط المَعلمات استنادًا إلى خصائص تطبيقك.

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

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 وقيمة nonce قبل إرسال طلبات الإعلانات.

/**
 * 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"، يمكنك الرجوع إلى مستندات الخادم لتسجيل قيمة nonce وإعادة توجيهها في كل طلب إعلان. يعرض المثال المقدَّم عنوان URL لطلب إعلان يتضمّن مَعلمة nonce. يتم نشر مَعلمة nonce من حزمة تطوير البرامج (SDK) لـ PAL، من خلال الخوادم الوسيطة، ثم إلى "مدير إعلانات Google"، ما يتيح تحقيق الربح بشكل أفضل.

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

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

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

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