إضافة إعلانات البانر الأصلية إلى تطبيق Android

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

سنقوم في هذا الدليل بتنفيذ موضع إعلان البانر الأصلي التالي. وسننشئ إعلان بانر أصليًا بالمكونات التالية:

خطوات إنشاء إعلان البانر الأصلي

الخطوة الأولى: طلب إعلان البانر الأصلي

الخطوة الثانية: إنشاء تخطيط إعلان البانر الأصلي الخاص بك

الخطوة الثالثة: تعبئة التخطيط باستخدام بيانات تعريف الإعلان

الخطوة الأولى: طلب إعلان البانر الأصلي

أضف الرمز البرمجي التالي أعلى فئة النشاط لديك لاستيراد مجموعة SDK لإعلانات Facebook:

import com.facebook.ads.*;

بعد ذلك، أنشئ مثيلًا للكائن NativeBannerAd وأنشئ AdListener وقم باستدعاء loadAd(...) في نشاطك:

public class NativeBannerAdActivity extends Activity {

    private final String TAG = NativeBannerAdActivity.class.getSimpleName();
    private NativeBannerAd nativeBannerAd;

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

        // Instantiate a NativeBannerAd object. 
        // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
        // now, while you are testing and replace it later when you have signed up.
        // While you are using this temporary code you will only get test ads and if you release
        // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
        nativeBannerAd = new NativeBannerAd(this, "YOUR_PLACEMENT_ID");
        NativeAdListener nativeAdListener = new NativeAdListener() {

            @Override
            public void onMediaDownloaded(Ad ad) {
                // Native ad finished downloading all assets
                Log.e(TAG, "Native ad finished downloading all assets.");
            }

            @Override
            public void onError(Ad ad, AdError adError) {
                // Native ad failed to load
                Log.e(TAG, "Native ad failed to load: " + adError.getErrorMessage());
            }

            @Override
            public void onAdLoaded(Ad ad) {
                // Native ad is loaded and ready to be displayed
                Log.d(TAG, "Native ad is loaded and ready to be displayed!");
            }

            @Override
            public void onAdClicked(Ad ad) {
                // Native ad clicked
                Log.d(TAG, "Native ad clicked!");
            }

            @Override
            public void onLoggingImpression(Ad ad) {
                // Native ad impression
                Log.d(TAG, "Native ad impression logged!");
            }
        });
        // load the ad
        nativeBannerAd.loadAd(
                nativeBannerAd.buildLoadAdConfig()
                        .withAdListener(nativeAdListener)
                        .build());
    }
}

سنعود لاحقًا لإضافة الرمز البرمجي إلى الأسلوب onAdLoaded().

الخطوة الثانية: إنشاء تخطيط إعلان البانر الأصلي الخاص بك

تتمثل الخطوة التالية في استخراج بيانات تعريف الإعلان واستخدام خصائصه لإنشاء واجهة مستخدم أصلية مخصصة. ويمكنك إنشاء طريقة عرض مخصصة في ملف تخطيط بتنسيق ‎.xml، أو يمكنك إضافة عناصر إلى الرمز البرمجي.

في تخطيط النشاط activity_main.xml لديك، أضف حاوية إلى إعلان البانر الأصلي لديك. ويجب أن تكون الحاوية com.facebook.ads.NativeAdLayout والتي تُعد أداة تغليف أعلى FrameLayout مزوّدة ببعض الوظائف الإضافية التي أتاحت لنا عرض تدفق تقارير الإعلانات الأصلية أعلى الإعلان. وفي الأسلوب onAdLoaded() لاحقًا، ستحتاج إلى تعبئة عرض إعلانك الأصلي في هذه الحاوية.

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    ...
    <com.facebook.ads.NativeAdLayout
        android:id="@+id/native_banner_ad_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_alignParentBottom="true" />
    ...
</RelativeLayout>

أنشئ تخطيطًا مخصصًا native_banner_ad_unit.xml لإعلان البانر الأصلي لديك:

فيما يلي مثال على التخطيط المخصص لإعلان البانر الأصلي لديك:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="horizontal">

        <RelativeLayout
            android:id="@+id/ad_choices_container"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:padding="2dp" />

        <TextView
            android:id="@+id/native_ad_sponsored_label"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_gravity="center_vertical"
            android:ellipsize="end"
            android:lines="1"
            android:padding="2dp"
            android:textColor="@android:color/darker_gray"
            android:textSize="12sp" />
    </LinearLayout>

    <RelativeLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:background="@android:color/white">

        <com.facebook.ads.MediaView
            android:id="@+id/native_icon_view"
            android:layout_width="50dp"
            android:layout_height="50dp"
            android:layout_alignParentLeft="true"
            android:layout_alignParentStart="true"
            android:gravity="center" />

        <LinearLayout
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_centerVertical="true"
            android:orientation="vertical"
            android:paddingLeft="53dp"
            android:paddingRight="83dp">

            <TextView
                android:id="@+id/native_ad_title"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:ellipsize="end"
                android:lines="1"
                android:textColor="@android:color/black"
                android:textSize="15sp"
                android:textStyle="bold" />

            <TextView
                android:id="@+id/native_ad_social_context"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:ellipsize="end"
                android:lines="1"
                android:textSize="12sp" />
        </LinearLayout>

        <Button
            android:id="@+id/native_ad_call_to_action"
            android:layout_width="80dp"
            android:layout_height="50dp"
            android:layout_alignParentEnd="true"
            android:layout_alignParentRight="true"
            android:background="#4286F4"
            android:gravity="center"
            android:paddingLeft="3dp"
            android:paddingRight="3dp"
            android:textColor="@android:color/white"
            android:textSize="12sp"
            android:visibility="gone" />

    </RelativeLayout>
</LinearLayout>

الخطوة الثالثة: تعبئة التخطيط باستخدام بيانات تعريف الإعلان

السيناريو الأول: اعرض الإعلان فورًا بمجرد تحميله بنجاح. وقم بتعديل الأسلوب onAdLoaded() أعلاه لاستعادة خصائص Native Banner Ad's وعرضها كما يلي:

public class NativeBannerAdActivity extends Activity {

    private NativeAdLayout nativeAdLayout;
    private LinearLayout adView;
    private NativeBannerAd nativeBannerAd;

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

        // Instantiate a NativeBannerAd object. 
        // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
        // now, while you are testing and replace it later when you have signed up.
        // While you are using this temporary code you will only get test ads and if you release
        // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
        nativeBannerAd = new NativeBannerAd(this, "YOUR_PLACEMENT_ID");
        NativeAdListener nativeAdListener = new NativeAdListener() {
            ...
            @Override
            public void onAdLoaded(Ad ad) {
                // Race condition, load() called again before last ad was displayed
                if (nativeBannerAd == null || nativeBannerAd != ad) {
                    return;
                 }
                // Inflate Native Banner Ad into Container
                inflateAd(nativeBannerAd);
            }
            ...
        });
        // load the ad
        nativeBannerAd.loadAd(
                nativeBannerAd.buildLoadAdConfig()
                        .withAdListener(nativeAdListener)
                        .build());
    }

    private void inflateAd(NativeBannerAd nativeBannerAd) {
        // Unregister last ad
        nativeBannerAd.unregisterView();

        // Add the Ad view into the ad container.
        nativeAdLayout = findViewById(R.id.native_banner_ad_container);
        LayoutInflater inflater = LayoutInflater.from(NativeBannerAdActivity.this);
        // Inflate the Ad view.  The layout referenced is the one you created in the last step.
        adView = (LinearLayout) inflater.inflate(R.layout.native_banner_ad_layout, nativeAdLayout, false);
        nativeAdLayout.addView(adView);

        // Add the AdChoices icon
        RelativeLayout adChoicesContainer = adView.findViewById(R.id.ad_choices_container);
        AdOptionsView adOptionsView = new AdOptionsView(NativeBannerAdActivity.this, nativeBannerAd, nativeAdLayout);
        adChoicesContainer.removeAllViews();
        adChoicesContainer.addView(adOptionsView, 0);

        // Create native UI using the ad metadata.
        TextView nativeAdTitle = adView.findViewById(R.id.native_ad_title);
        TextView nativeAdSocialContext = adView.findViewById(R.id.native_ad_social_context);
        TextView sponsoredLabel = adView.findViewById(R.id.native_ad_sponsored_label);
        MediaView nativeAdIconView = adView.findViewById(R.id.native_icon_view);
        Button nativeAdCallToAction = adView.findViewById(R.id.native_ad_call_to_action);

        // Set the Text.
        nativeAdCallToAction.setText(nativeBannerAd.getAdCallToAction());
        nativeAdCallToAction.setVisibility(
                nativeBannerAd.hasCallToAction() ? View.VISIBLE : View.INVISIBLE);
        nativeAdTitle.setText(nativeBannerAd.getAdvertiserName());
        nativeAdSocialContext.setText(nativeBannerAd.getAdSocialContext());
        sponsoredLabel.setText(nativeBannerAd.getSponsoredTranslation());

        // Register the Title and CTA button to listen for clicks.
        List<View> clickableViews = new ArrayList<>();
        clickableViews.add(nativeAdTitle);
        clickableViews.add(nativeAdCallToAction);
        nativeBannerAd.registerViewForInteraction(adView, nativeAdIconView, clickableViews);
    }
}

ستسجّل مجموعة SDK عدد مرات ظهور الإعلان وتعالج النقرة تلقائيًا. لذا يرجى ملاحظة أنه يجب تسجيل طريقة عرض الإعلان بالمثيل NativeBannerAd لتمكين ذلك. ولجعل عناصر إعلانك قابلة للنقر، يمكنك تسجيلها باستخدام:

registerViewForInteraction(View view, MediaView adIconView)

السيناريو الثاني: اعرض الإعلان خلال بضع ثوان أو دقائق بعد تحميله بنجاح. ويجب التحقق مما إذا كان الإعلان قد تم إبطاله قبل عرضه أم لا.

يجب عليك متابعة الفكرة أدناه، ولكن يرجى عدم نسخ الرمز البرمجي في مشروعك لأنه مجرد مثال:

public class NativeBannerAdActivity extends Activity {

    private NativeBannerAd nativeBannerAd;

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

        // Instantiate a NativeBannerAd object. 
        // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
        // now, while you are testing and replace it later when you have signed up.
        // While you are using this temporary code you will only get test ads and if you release
        // your code like this to the Google Play your users will not receive ads (you will get a no fill error).
        nativeBannerAd = new NativeBannerAd(this, "YOUR_PLACEMENT_ID");
         NativeAdListener nativeAdListener = new NativeAdListener() {
            ...
        });
        // load the ad
        nativeBannerAd.loadAd(
                nativeBannerAd.buildLoadAdConfig()
                        .withAdListener(nativeAdListener)
                        .build());
    }

    private void showAdWithDelay() {
       /**
        * Here is an example for displaying the ad with delay;
        * Please do not copy the Handler into your project
       */
       // Handler handler = new Handler();
       handler.postDelayed(new Runnable() {
           public void run() {
             // Check if nativeBannerAd has been loaded successfully
               if(nativeBannerAd == null || !nativeBannerAd.isAdLoaded()) {
                   return;
               }
             // Check if ad is already expired or invalidated, and do not show ad if that is the case. You will not get paid to show an invalidated ad.
               if(nativeBannerAd.isAdInvalidated()) {
                   return;
               }
               inflateAd(nativeBannerAd); // Inflate Native Banner Ad into Container same as in previous code example
           }
       }, 1000 * 60 * 15); // Show the ad after 15 minutes
    }
}

التحكم في المساحة القابلة للنقر عليها

للتحكم بصورة أدق في العناصر التي يمكن النقر عليها، يمكنك استخدام registerViewForInteraction(View view, MediaView adIconView, List<View> clickableViews) لتسجيل قائمة بطرق العرض التي يمكن النقر عليها. فعلى سبيل المثال، إذا كنت لا تريد سوى جعل عنوان الإعلان وزر الدعوة لاتخاذ إجراء يمكن النقر عليهما في المثال السابق، يمكنك الكتابة بالطريقة التالية:

@Override
public void onAdLoaded(Ad ad) {
  ...
  List<View> clickableViews = new ArrayList<>();
  clickableViews.add(nativeAdTitle);
  clickableViews.add(nativeAdCallToAction);
  nativeBannerAd.registerViewForInteraction(mAdView, nativeAdIconView, clickableViews);
  ...
}

في الحالات التي تعيد فيها استخدام طريقة العرض من أجل عرض إعلانات مختلفة بمرور الوقت، تأكد من استدعاء unregisterView() قبل تسجيل طريقة العرض نفسها بمثيل NativeBannerAd مختلف.

قم بتشغيل الرمز البرمجي ويتعين عليك عرض إعلان البانر الأصلي:

• يمكنك الرجوع إلى دليل قالب الإعلان الأصلي لإضافة إعلانات أصلية في تطبيقك.

• استكشف عينات من الرموز البرمجية التي توضح كيفية استخدام الإعلانات الأصلية. ويتوفر NativeBannerAdSample كجزء من مجموعة SDK ويمكن العثور عليه ضمن المجلد AudienceNetwork/samples. وقم باستيراد المشروع إلى IDE وتشغيله على أي جهاز أو على المحاكي.