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

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

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

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

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

الإعداد

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

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

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

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

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

  • الخطوة 23 والإجراءات اللاحقة: أثناء عرض إعلانك، أبلِغ حزمة 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 إلا بـ 3 أرقام. ولتجنُّب هذه المشكلة، ننصح بدمج آخر رقمَين في رقم إصدار التصحيح، كما هو موضّح أدناه.

@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. يتم إعادة توجيه هذا الإجراء إلى ناشري التطبيقات لكي يعرفوا أنّه يمكنهم بدء تحميل الإعلانات.

@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 في الوقت نفسه إشارات من جميع برامج التكييف المشاركة في عروض الأسعار. يُرجى احترام هذا الوقت وعدم إجراء أي مكالمات إلى سلسلة UI الرئيسية خلاله. يجب تنفيذ أي عمل مكثّف يحتاج إليه المحوّل أو حزمة تطوير البرامج (SDK) لجمع الإشارات في طريقة initialize() وتخزينها مؤقتًا.

بعد أن تصبح الإشارات جاهزة، استدعِ وظيفة onSuccess() callback مع الإشارات المرمّزة.

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

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

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

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

المهلة: 10 ثوانٍ

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

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

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

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

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

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

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

بعد أن تحمّل حزمة SDK الإعلان، اتّصِل بالرقم mediationAdLoadCallback.onSuccess(). في حال تعذُّر تحميل الإعلان عن الحدث، استدعِ الدالة 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 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 في معاودة الاتصال الناجحة للتحميل، حتى تتمكّن حزمة تطوير البرامج لإعلانات Google على الأجهزة الجوّالة من أن تطلب من محوّل الشبكة عرض الإعلان.

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

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

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

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

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

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

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, ...);
  }
}