البدء

تتيح لك ميزة PAL إرسال إشارات إعلانات Google في طلبات الإعلانات وأثناء تشغيل الإعلانات.

يغطّي هذا الدليل عملية إضافة حزمة تطوير البرامج (SDK) الخاصة بـ PAL على Android إلى تطبيقك. وللاطّلاع على نموذج تطبيق يستخدم PAL لإنشاء رقم عشوائي، يمكنك تنزيل مثال Android من GitHub.

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

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

implementation 'com.google.android.gms:play-services-pal:22.1.0'
build.gradle

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

إنشاء رقم عشوائي

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

  1. استورِد PAL وأعدّها باتّباع الخطوات التالية:

    1. استيراد صفوف PAL:

      import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;
import java.util.HashSet;
import java.util.Set;

      MainActivity.java

    2. أنشئ متغيّرات خاصة لتخزين مثيلات NonceLoader وNonceManager:

      private NonceLoader nonceLoader;
private NonceManager nonceManager;
      MainActivity.java

    3. ابدأ مثيل NonceLoader باستخدام مثيل ConsentSettings في الطريقة onCreate:

      @Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  // 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 isStorageAllowed = getConsentToStorage();

  ConsentSettings consentSettings =
      ConsentSettings.builder().allowStorage(isStorageAllowed).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);

  adClickButton = findViewById(R.id.send_click_button);

  logView = findViewById(R.id.log_view);
  logView.setMovementMethod(new ScrollingMovementMethod());
}

      MainActivity.java

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

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

  2. إنشاء رقم عشوائي:

    public void generateNonceForAdRequest(View view) {
  logMessage("Generate Nonce Request");
  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();

  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(
          new OnSuccessListener<NonceManager>() {
            @Override
            public void onSuccess(NonceManager manager) {
              nonceManager = manager;
              String nonceString = manager.getNonce();
              logMessage("Nonce generated");
              logMessage(nonceString.substring(0, 20) + "...");
              Log.i(LOG_TAG, "Generated nonce: " + nonceString);

              // From here you would trigger your ad request and move on to initialize content.
              exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);

              adClickButton.setEnabled(true);
            }
          })
      .addOnFailureListener(
          new OnFailureListener() {
            @Override
            public void onFailure(Exception error) {
              logMessage("Nonce generation failed");
              Log.e(LOG_TAG, "Nonce generation failed: " + error.getMessage());
            }
          });
}

    MainActivity.java

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

    تنشئ هذه الدالة رقمًا عشوائيًا غير متزامن. يجب التعامل مع حالات النجاح والفشل في طلب الرقم العشوائي. بعد توفّر أداة إدارة الأرقام العشوائية، استرجِع الرقم العشوائي قبل تقديم طلب إعلان باستخدام الطريقة nonceManager.getNonce().

إرفاق قيمة nonce بطلب الإعلان

لاستخدام الرقم العشوائي الذي تم إنشاؤه، أضِف مَعلمة givn إلى علامة الإعلان وقيمة الرقم العشوائي قبل تقديم طلبات الإعلان:

// From here you would trigger your ad request and move on to initialize content.
exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
MainActivity.java

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

لتتبُّع أحداث التشغيل، يجب إعداد معالِجات الأحداث لإرسال إشارات الإعلانات إلى Google باتّباع الخطوات التالية:

// Triggered when a user clicks-through on an ad which was requested using a PAL nonce.
public void sendAdClick(View view) {
  logMessage("Ad click sent");
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

// In a typical PAL app, this is called when a user touch or click is detected,
// on the ad other than an ad click-through.
public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendAdTouch(e);
  }
}

// In a typical PAL app, this is called when a content playback session starts.
public void sendPlaybackStart() {
  logMessage("Playback start");
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

// In a typical PAL app, this is called when a content playback session ends.
public void sendPlaybackEnd() {
  logMessage("Playback end");
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

MainActivity.java

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

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

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

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

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

اضبط خادم الإعلانات التابع لجهة خارجية على تضمين الرقم العشوائي في طلب الخادم إلى &quot;إدارة الإعلانات&quot;. في ما يلي مثال على علامة إعلان تم إعدادها داخل خادم الإعلانات الخارجي:

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

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

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