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

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

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

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

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

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

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

الخطوة الرابعة: استخدام MediaView

الخطوة الخامسة: تحميل إعلان بدون تخزين مؤقت تلقائي

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

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

import com.facebook.ads.*;

بعد ذلك، أنشئ مثيلاً للكائن NativeAd وأنشئ NativeAdListener وقم باستدعاء loadAd() باستخدام متتبع أداء الإعلان:

private final String TAG = "NativeAdActivity".getClass().getSimpleName();
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd 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).
    nativeAd = new NativeAd(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!");
        }
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());
}

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

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

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

في تخطيط نشاطك activity_main.xml، أضف حاوية لـ Native Ad. ويجب أن تكون الحاوية com.facebook.ads.NativeAdLayout والتي تُعد أداة تضمين أعلى FrameLayout مزوّدة ببعض الوظائف الإضافية التي أتاحت لنا عرض تدفق تقارير الإعلانات الأصلية أعلى الإعلان.

<?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"
    android:gravity="center_horizontal"
    android:paddingTop="50dp">
    ...
    <ScrollView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:paddingBottom="50dp">

        <com.facebook.ads.NativeAdLayout
             android:id="@+id/native_ad_container"
             android:layout_width="match_parent"
             android:layout_height="wrap_content"
             android:orientation="vertical" />
     </ScrollView>
    ...
</RelativeLayout>

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

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

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/ad_unit"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@android:color/white"
    android:orientation="vertical"
    android:paddingLeft="10dp"
    android:paddingRight="10dp">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="horizontal"
        android:paddingBottom="10dp"
        android:paddingTop="10dp">

        <com.facebook.ads.MediaView
            android:id="@+id/native_ad_icon"
            android:layout_width="35dp"
            android:layout_height="35dp" />

        <LinearLayout
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:orientation="vertical"
            android:paddingLeft="5dp"
            android:paddingRight="5dp">

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

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

    </LinearLayout>

    <LinearLayout
        android:id="@+id/ad_choices_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="end"
        android:orientation="horizontal" />

    </LinearLayout>

    <com.facebook.ads.MediaView
        android:id="@+id/native_ad_media"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="center" />

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

        <LinearLayout
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_weight="3"
            android:orientation="vertical">

            <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:textColor="@android:color/darker_gray"
                android:textSize="12sp" />

            <TextView
                android:id="@+id/native_ad_body"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:ellipsize="end"
                android:gravity="center_vertical"
                android:lines="2"
                android:textColor="@android:color/black"
                android:textSize="12sp" />

        </LinearLayout>

        <Button
            android:id="@+id/native_ad_call_to_action"
            android:layout_width="100dp"
            android:layout_height="30dp"
            android:layout_gravity="center_vertical"
            android:layout_weight="1"
            android:background="#4286F4"
            android:paddingLeft="3dp"
            android:paddingRight="3dp"
            android:textColor="@android:color/white"
            android:textSize="12sp"
            android:visibility="gone" />

    </LinearLayout>

</LinearLayout>

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

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

private NativeAdLayout nativeAdLayout;
private LinearLayout adView;
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd 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).
    nativeAd = new NativeAd(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 (nativeAd == null || nativeAd != ad) {
                return;
            }
            // Inflate Native Ad into Container
            inflateAd(nativeAd);
        }
        ...
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());
}

private void inflateAd(NativeAd nativeAd) {

    nativeAd.unregisterView();

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

    // Add the AdOptionsView
    LinearLayout adChoicesContainer = findViewById(R.id.ad_choices_container);
    AdOptionsView adOptionsView = new AdOptionsView(NativeAdActivity.this, nativeAd, nativeAdLayout);
    adChoicesContainer.removeAllViews();
    adChoicesContainer.addView(adOptionsView, 0);

    // Create native UI using the ad metadata.
    MediaView nativeAdIcon = adView.findViewById(R.id.native_ad_icon);
    TextView nativeAdTitle = adView.findViewById(R.id.native_ad_title);
    MediaView nativeAdMedia = adView.findViewById(R.id.native_ad_media);
    TextView nativeAdSocialContext = adView.findViewById(R.id.native_ad_social_context);
    TextView nativeAdBody = adView.findViewById(R.id.native_ad_body);
    TextView sponsoredLabel = adView.findViewById(R.id.native_ad_sponsored_label);
    Button nativeAdCallToAction = adView.findViewById(R.id.native_ad_call_to_action);

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

    // Create a list of clickable views
    List<View> clickableViews = new ArrayList<>();
    clickableViews.add(nativeAdTitle);
    clickableViews.add(nativeAdCallToAction);

    // Register the Title and CTA button to listen for clicks.
    nativeAd.registerViewForInteraction(
            adView, nativeAdMedia, nativeAdIcon, clickableViews);
}

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

registerViewForInteraction(View view, MediaView adMediaView, MediaView adIconView)

عند استخدام registerViewForInteraction مع NativeAds، تتحقق مجموعة SDK من تشغيل الاستدعاء في سلسلة المنشورات الأساسية لتجنب حالات التعارض. وننفذ عملية التحقق باستخدام Preconditions.checkIsOnMainThread(). يُرجى التأكد من امتثال التنفيذ لهذا المعيار حيث إن تطبيقك سيتعطل إذا حاولت استدعاء registerViewForInteraction من سلسلة المنشورات في الخلفية.

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

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

private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd 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).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");

    NativeAdListener nativeAdListener = new NativeAdListener() {
        ...
    };

    // Request an ad
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .build());

    // Here is just an example for displaying the ad with delay
    // Please call this method at appropriate timing in your project
    showNativeAdWithDelay();
}

private void showNativeAdWithDelay() {
    /**
     * 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 nativeAd has been loaded successfully
            if(nativeAd == null || !nativeAd.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(nativeAd.isAdInvalidated()) {
                return;
            }
            inflateAd(nativeAd); // Inflate NativeAd into a container, same as in previous code examples
        }
    }, 1000 * 60 * 15); // Show the ad after 15 minutes
}

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

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

@Override
public void onAdLoaded(Ad ad) {
    ...
    // Create a list of clickable views
    List<View> clickableViews = new ArrayList<>();
    clickableViews.add(nativeAdTitle);
    clickableViews.add(nativeAdCallToAction);

    // Register the Title and CTA button to listen for clicks.
    nativeAd.registerViewForInteraction(
            adView, nativeAdMedia, nativeAdIcon, clickableViews);
    ...
}

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

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

الخطوة الرابعة: استخدام MediaView

لعرض صورة غلاف الإعلان الأصلي، يجب استخدام MediaView من Meta Audience Network والتي يمكنها عرض كل من أصول الصور والفيديو. يمكنك مراجعة إرشادات التصميم التي نوفرها حول وحدات إعلان الفيديو الأصلي من هنا.

بشكل افتراضي، يتم تخزين أصول الصورة والفيديو كلها مؤقتًا بشكل مسبق عند تحميل الإعلانات الأصلية والتي تعمل على تمكين MediaView لتشغيل مقاطع الفيديو على الفور بعد انتهاء nativeAd من التحميل.

private void loadNativeAd() {
    ...
    nativeAd.loadAd();
}

كما يمكنك بوضوح تحديد NativeAd.MediaCacheFlag.ALL عند تحميل الإعلانات الأصلية.

private void loadNativeAd() {
    ...
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withMediaCacheFlag(NativeAdBase.MediaCacheFlag.ALL)
                    .build());
}

تدعم Audience Network خياري تخزين مؤقت في الإعلانات الأصلية كما هو موضح في تعداد NativeAd.MediaCacheFlag:

الخطوة الخامسة: تحميل إعلان بدون تخزين مؤقت تلقائي

• نوصي بشدة بالاحتفاظ بالتخزين المؤقت للوسائط قيد التشغيل افتراضيًا في كل الحالات. ومع ذلك، نسمح لك بتخطي الإعداد الافتراضي من خلال استخدام MediaCacheFlag.NONE في الأسلوب loadAd. يُرجى توخي الحذر إذا قررت تخطي تخزين الوسائط المؤقت الافتراضي.

private final String TAG = NativeAdActivity.class.getSimpleName();
private NativeAd nativeAd;

private void loadNativeAd() {
    // Instantiate a NativeAd 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).
    nativeAd = new NativeAd(this, "YOUR_PLACEMENT_ID");
    NativeAdListener nativeAdListener = new NativeAdListener() {
        ...
    };

    // Request an ad without auto cache
    nativeAd.loadAd(
            nativeAd.buildLoadAdConfig()
                    .withAdListener(nativeAdListener)
                    .withMediaCacheFlag(NativeAdBase.MediaCacheFlag.NONE)
                    .build());
}

• بعد استدعاء onAdLoaded بنجاح في الإعلان، يمكنك استدعاء الأسلوب downloadMedia يدويًا لبدء تنزيل كل الوسائط للإعلان الأصلي عند الاقتضاء.

@Override
public void onAdLoaded(Ad ad) {
    if (nativeAd == null || nativeAd != ad) {
        return;
    }

    nativeAd.downloadMedia();
}

• وأخيرًا، يمكنك استدعاء الأسلوب registerViewForInteraction وعرض الإعلان عندما تنتهي الوسائط من التحميل في الاستدعاء onMediaDownloaded.

@Override
public void onMediaDownloaded(Ad ad) {
    if (nativeAd == null || nativeAd != ad) {
        return;
    }

    inflateAd(nativeAd); // Inflate NativeAd into a container, same as in previous code examples
}

إذا تم تحميل الإعلان بدون التخزين المؤقت التلقائي ولم تقم باستدعاء downloadMedia يدويًا لبدء التنزيل، فسيتم بدأ تنزيل الوسائط فقط عند استدعاء registerViewForInteraction. يجب تحميل كل الوسائط وعرضها للحصول على مرة ظهور إعلان مؤهلة.

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

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