البدء

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

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

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

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

implementation("com.google.android.gms:play-services-pal:23.1.0")

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

تفعيل إزالة السكر من التطبيق

بدءًا من الإصدار 23.0.0، يتطلّب PAL تفعيل ميزة إلغاء السكرية في التطبيق، وذلك من خلال ضبط coreLibraryDesugaringEnabled true وإضافة تبعية إلى com.android.tools:desugar_jdk_libs في ملف build.gradle. لمزيد من التفاصيل، يُرجى الاطّلاع على واجهات برمجة تطبيقات Java 11 والإصدارات الأحدث المتاحة من خلال إزالة التجميل اللغوي باستخدام مواصفات nio.

coreLibraryDesugaringEnabled = true

إنشاء رقم خاص

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

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

      private NonceLoader nonceLoader;
private NonceManager nonceManager;

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

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

  // By default, PAL automatically determines whether to enable limited ads
  // based on the user's TCF (Transparency and Consent Framework) consent data
  // on the device. If you must manually override the default behavior,
  // for example, to meet your app's requirements, use the
  // `ConsentSettings.Builder.forceLimitedAds` property.
  ConsentSettings consentSettings = ConsentSettings.builder().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());
}

    في تطبيقك، أنشئ مثيلاً واحدًا لفئة 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());
            }
          });
}

    تحتاج إلى رقم خاص واحد فقط لجميع طلبات عرض الإعلان في عملية تشغيل بث واحد. لأغراض الاختبار، استدعِ هذه الدالة عند النقر على زر في تطبيق الاختبار. إنّ مَعلمات 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);

إذا كنت تطلب إعلانات وتعرضها من Google، عليك عرض رمز AdChoices والتراكب. للحصول على تفاصيل حول تحليل استجابة VAST وعرض الرموز، يُرجى الاطّلاع على رمز "خيارات الإعلان" والتراكب.

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

لتتبُّع أحداث التشغيل، يجب إعداد معالجات الأحداث لإرسال إشارات الإعلانات إلى 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();
  }
}

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

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

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

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

عند إعداد خادم إعلانات من جهة خارجية للعمل مع "إدارة إعلانات Google"، يُرجى الرجوع إلى مستندات الخادم لتسجيل قيمة 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= لتحديد قيمة الرقم العشوائي. يجب أن يتيح خادم الإعلانات التابع لجهة خارجية استخدام بعض وحدات الماكرو الخاصة به، مثل %%custom_key_for_google_nonce%%، وأن يستبدلها بمَعلمة طلب البحث الخاصة برقم الاستخدام لمرة واحدة التي قدّمتها في الخطوة السابقة. تتوفّر معلومات إضافية حول كيفية تنفيذ ذلك في مستندات خادم الإعلانات التابع لجهة خارجية.