تطوير محوِّل عروض الأسعار

هذا الدليل مخصّص للشبكات الإعلانية التي تريد إنشاء محوِّل عروض أسعار للمشاركة في عروض الأسعار في الوقت الفعلي (RTB) ضمن توسّط Google. إذا كنت ناشرًا، يُرجى الاطّلاع على تعليمات توسّط الناشر.

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

لكي تعمل عروض الأسعار بشكل صحيح، يجب أن يعالج المحوِّل عمليات الإعداد وجمع الإشارات وتحميل الإعلانات وإعادة توجيه أحداث رحلة الإعلان. في هذا الدليل، سنرشدك إلى كيفية تنفيذ المحوِّل لمعالجة هذه العمليات.

ملاحظة: تتطلّب المشاركة في عروض الأسعار أيضًا مقدّم عروض أسعار يمكنه الاستجابة لطلبات OpenRTB. إنّ التعليمات حول كيفية إعداد مقدّم عروض أسعار تقع خارج نطاق هذا الدليل.

سير عمل محوِّل عروض الأسعار

الإعداد

في ما يلي عملية تفصيلية لدورة حياة الطلبات والاستجابات وعرض المحتوى للمحوِّل:

يتحمّل المحوِّل مسؤولية الأجزاء التالية من سير العمل:

• الخطوات 4 إلى 7: إعداد المحوِّل وإعادة طلب حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" بعد اكتمال عملية الإعداد

• الخطوات 10 إلى 13: جمع الإشارات من حزمة تطوير البرامج (SDK) لشبكة المواقع الإعلانية لإرسالها إلى مقدّم عروض الأسعار للمشاركة في طلب عروض أسعار في الوقت الفعلي، وإعادة توجيهها إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة

• الخطوات 18 إلى 21: إذا أرجع نظام عروض الأسعار عرض السعر الفائز، حمِّل الإعلان وفقًا للردّ من نظام عروض الأسعار. بعد التحميل، أطلِع حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" على أنّه تم تحميل الإعلان.

• الخطوة 23 والخطوات اللاحقة: أثناء عرض إعلانك، أرسِل إشعارًا إلى "حزمة SDK لإعلانات Google على الأجهزة الجوّالة" بشأن أحداث مرّات الظهور والنقرات، بالإضافة إلى أحداث الإعلانات الأخرى التي تحدث أثناء دورة عرض إعلانك.

ملاحظة: تتتبّع حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة أحداث مرّات الظهور بشكل منفصل، ولكن من المهم أيضًا إعادة توجيه حدث مرّة الظهور في شبكة المواقع الإعلانية لكي تتمكّن من التحقّق من أيّ تناقضات.

تنفيذ محوِّل عروض الأسعار

لإنشاء محوِّل عروض أسعار لحزمة "SDK لإعلانات Google على الأجهزة الجوّالة"، عليك توسيع الفئة المجردة RtbAdapter. توضّح الأقسام التالية كل طريقة مجردة في RtbAdapter.

getSDKVersionInfo()

يجب هنا إدخال إصدار حزمة SDK. ويتم تمرير هذا الإصدار إلى مقدّم عروض الأسعار كجزء من طلب OpenRTB.

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

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

عليك هنا إدخال إصدار المحوِّل. ويتم تمرير هذا الإصدار إلى مقدّم عروض الأسعار كجزء من طلب OpenRTB.

تستخدم محوِّلات Google ذات المصدر المفتوح والإصدارات المختلفة مخطّطًا لإصدار المحوِّل يتألّف من 4 أرقام، ولكن لا يسمح VersionInfo إلا بثلاثة أرقام. لحلّ هذه المشكلة، يُنصح بدمج الرقمَين الأخيرَين في إصدار التصحيح، كما هو موضّح أدناه.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

مهلة الانتظار: 30 ثانية

الطريقة initialize() هي الطريقة الأولى التي يتمّ استدعاؤها في المُحوِّل. ويتم استدعاؤه مرة واحدة فقط في كل جلسة. تمنحك هذه الطريقة قائمة بعناصر MediationConfiguration التي تمثّل القائمة الكاملة ل المواضع في هذا التطبيق التي تم ضبطها لشبكتك الإعلانية. ويمكنك التمرير في هذه القائمة لتحليل بيانات الاعتماد لكل موضع إعلان، وإرسال البيانات ذات الصلة إلى حزمة SDK لإعدادها.

بعد بدء حزمة SDK واستعدادها لتلقّي طلبات الإعلانات، يمكنك استدعاء onInitializationSucceeded()InitializationCompleteCallback. ويتم إعادة توجيه طلب إعادة الاتصال هذا إلى ناشري التطبيقات حتى يعرفوا أنّه يمكنهم بدء تحميل الإعلانات.

ملاحظة: يتمّ استدعاء طريقة initialize() على مثيل مخصّص للاستخدام مرة واحدة من محوِّل. ولن يتم استدعاء أي طرق أخرى في هذه الحالة المحدّدة. إذا كان المحوِّل يحتاج إلى حفظ الحالة نتيجةً لهذه الطريقة، يجب أن تكون أي حالة ثابتة.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

مهلة الانتظار: ثانية واحدة

في كل مرة يطلب فيها الناشر إعلانًا، يتم إنشاء مثيل جديد من RtbAdapter ويتم استدعاء الطريقة collectSignals(). سيتم استخدام مثيل RtbAdapter هذا طوال دورة حياة طلب الإعلان والاستجابة له وعرضه. تتيح طريقة collectSignals() لجهاز التحكّم في المقترِح تقديم إشارات من الجهاز لإرسالها إلى مقدّم عروض الأسعار في طلب OpenRTB.

يتم استدعاء collectSignals() في سلسلة محادثات في الخلفية. تطلب حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" في الوقت نفسه إشارات من جميع المحوِّلات المشارِكة في تقديم عروض الأسعار. يُرجى احترام هذه الفترة وحصر المكالمات بخيط واجهة المستخدم. يجب تنفيذ أي عمل شاق يحتاجه المحوِّل أو حزمة SDK لجمع الإشارات في طريقة initialize() وتخزينها مؤقتًا.

بعد أن تصبح الإشارات جاهزة، اتصل بـ onSuccess() لتلقّي مكالمة تلقائية تتضمّن الإشارات المشفّرة.

في ما يلي مثال على التنفيذ:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

إذا تعذّر على المحوِّل جمع الإشارات، اتصل على signalCallbacks.onFailure() مع تضمين سلسلة توضّح الخطأ الذي حدث.

ملاحظة: يمكن أن تمثّل سلسلة الإشارات أي عنصر، ويمكن أن تكون بأي تنسيق، مثل تنسيق JSON العادي أو تنسيق Base64 المشفّر أو أي شكل آخر من أشكال التشفير الذي تختاره. ننصح بتشفير الإشارات لضمان عدم شفافيتها خارج شبكتك.

تنفيذ طرق تحميل الإعلانات

مهلة الانتظار: 10 ثوانٍ

إذا أرجع مقدّم عروض الأسعار عرض السعر الفائز، تُطلِق حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" محوِّل البيانات لتحميل الإعلان الفائز، مع إرسال أي بيانات أرجعها مقدّم عروض الأسعار والتي تحتاجها حزمة SDK لتحميل هذا الإعلان.

تعتمد طريقة التحميل الدقيقة التي يتمّ استدعاؤها على تنسيق الإعلان الذي يخصّه هذا الطلب:

شكل الإعلان	طريقة التحميل
بانر	loadBannerAd()
إعلان بيني	loadInterstitialAd()
تم منح المكافأة	loadRewardedAd()

طبِّق هذه الطرق على أشكال الإعلانات التي يتوافق معها المحوِّل.

يتم استدعاء طريقة load في سلسلة مهام واجهة المستخدم، في النسخة نفسها من المحوِّل الذي قدّمت الإشارات منه. تقدّم لك هذه الطريقة الجدول التالي الذي يعرض المَعلمات التالية:

• MediationAdConfiguration، الذي يحتوي على مَعلمات تحتاجها حزمة SDK لتحميل الإعلان لعرض السعر الفائز، مثل استجابة عرض السعر وأيّ بيانات اعتماد أعدّها الناشر في واجهة مستخدم AdMob

• عنصر MediationAdLoadCallback المستخدَم لإعلام حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" عند نجاح التحميل أو تعذّره

بعد أن تحمّل حزمة SDK الإعلان، يمكنك الاتصال بـ mediationAdLoadCallback.onSuccess(). في حال تعذّر loading ad في الحدث، يمكنك الاتصال بالرقم mediationAdLoadCallback.onFailure() مع إرسال سلسلة توضّح الخطأ الذي حدث.

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

يحتوي MediationAdConfiguration أيضًا على getWatermark() طريقة لعرض سلسلة بترميز base64 تمثّل صورة بتنسيق PNG. يجب أن تكون هذه الصورة مُجمَّعة في شاشة شفافة على إعلاناتك. يمكنك التواصل مع Google للحصول على إرشادات إضافية حول كيفية عرض العلامة المائية. يحتوي على بيانات وصفية عن الإعلان الذي يتم عرضه ليستخدمها الناشرون لتحديد مصدر الإعلانات المعروضة.

بالنسبة إلى إعلانات البانر، سيُطلب منك تقديم عرض البانر. بالنسبة إلى الإعلانات البينية و الإعلانات التي تضم مكافآت، سيُطلب منك تنفيذ طريقة show() لعرض الإعلان في وقت لاحق. كإحدى أفضل الممارسات، ننصحك بجعل فئة التطبيق التي تُجري تحميل الإعلان مسؤولة أيضًا عن تنفيذ طرق عرض الإعلانات هذه.

في ما يلي نموذج لتنفيذ loadBannerAd(). يُرجى العِلم أنّ عملية تنفيذ المحوِّل ستبدو مختلفة، لأنّ المحوِّل يتم دمجه مع حزمة SDK مختلفة.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to the Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

أحداث مراحل نشاط عرض الإعلانات

تتمثل المسؤولية النهائية للمحوِّل في إرسال إشعار إلى "حزمة SDK لإعلانات Google على الأجهزة الجوّالة" بشأن أيّ أحداث دورة حياة عرض، حتى يمكن إعادة توجيهها إلى الناشر. يتوقّع الناشر تلقّي هذه الاستدعاءات في أوقات محدّدة بغض النظر عن الشبكة الإعلانية التي تعرِض الإعلان، لذا من المهمّ استدعاء أكبر عدد ممكن من هذه الاستدعاءات في الوقت المناسب كي تتمكّن حزمة SDK لإعلانات Google على الأجهزة الجوّالة من إعادة توجيهها إلى الناشر.

يجب أن تستدعي المحوِّلات الأحداث التالية عند الاقتضاء:

الأحكام الشائعة لجميع التنسيقات
الطريقة	حالات الاتصال
reportAdClicked()	تم النقر على الإعلان.
reportAdImpression()	عرض الإعلان مرّة ظهور.
onAdOpened()	عرض الإعلان طريقة عرض بملء الشاشة.
onAdClosed()	تم إغلاق عرض الإعلان بملء الشاشة.
onAdLeftApplication()	تسبّب الإعلان في مغادرة المستخدم للتطبيق.
الإعلانات التي تضم مكافأة
onRewarded()	يحصل المستخدم على مكافأة.
عمليات معاودة الاتصال عبر الفيديو (إعلانات الفيديو التي تضم مكافآت وإعلانات مدمجة مع المحتوى)
onVideoStarted()	بدأ فيديو الإعلان.
onVideoCompleted()	اكتمال عرض فيديو الإعلان

يتلقّى المحوِّل MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> كائنًا عند الاتصال mediationAdLoadCallback.onSuccess(). من المفترض أن تحتفظ المحوِّلات بهذا العنصر وتستخدمه لاستدعاء أحداث العرض التي تحدث في إعلانك.

وعادةً ما تكون معظم هذه الأحداث مستندة إلى حزمة تطوير البرامج (SDK) لشبكة المواقع الإعلانية. إنّ دور الادّابتر هو ربط عمليات الاستدعاء من حزمة تطوير البرامج (SDK) لشبكة الإعلانات بحزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.

يوضّح المثال التالي كيفية إعادة توجيه عمليات تسجيل الإحالات الناجحة من مستمع الإعلانات في حزمة تطوير البرامج (SDK) إلى "حزمة SDK لإعلانات Google على الأجهزة الجوّالة":

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

مواد العرض المطلوبة لتتبُّع مرّات ظهور الإعلانات المدمجة مع المحتوى

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

اطّلِع على مستندات مواد العرض المطلوبة المدمجة للحصول على مزيد من المعلومات عن كيفية تحديد مواد عرض مطلوبة إضافية في ردّ ملف العروض التسعيرية.

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

عرض أخطاء الإعلانات

بالنسبة إلى التنسيقات التي تظهر على الشاشة الكاملة، مثل الإعلانات البينية والإعلانات التي تضمّ مكافأة، عليك توفير تنفيذ لدالّة MediationInterstitialAd أو MediationRewardedAd في دالة callback الخاصة بالتحميل (success) كي تتمكّن حزمة SDK لإعلانات Google على الأجهزة الجوّالة من طلب عرض الإعلان من المحوِّل.

تتوقّع حزمة SDK لإعلانات Google على الأجهزة الجوّالة أنّه إذا حمّل محوِّل إعلانًا بنجاح، سيكون الإعلان جاهزًا للعرض عندما يطلب الناشر عرضه. وهذا يعني أنّه يجب أن تؤدّي كلّ طلب عرض إلى ظهور إعلان.

ومع ذلك، قد تكون هناك حالات استثنائية يتعذّر فيها عرض إعلان. إذا تعذّر عليك عرض الإعلان، يمكنك الاتصال بالإجراء المُعاد تدويره onAdFailedToShow() لإلغاء مرّة الظهور.

يوضّح الجدول التالي كيفية تأثير عمليات تسجيل الإحالات الناجحة في تسجيل مرّات الظهور لأشكال الإعلانات التي تظهر على الشاشة الكاملة:

معاودة الاتصال	النتيجة
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
لا شيء مما سبق لعدة ثوانٍ	Impression recorded

¹ بالنسبة إلى مرّات الظهور التي تعذّر عرضها، لا يتم تحصيل رسوم من شبكة الإعلانات مقابل مرّة الظهور، ولكنّها تؤثر في تعديل معدّل الأحداث الخاضعة للفوترة. اطّلِع على إشارات طلب عروض الأسعار للحصول على مزيد من المعلومات.

يوضّح المثال التالي دورة تحميل/عرض قد يؤدي فيها طلب عرض الإعلان إلى حدوث خطأ.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}