راه‌اندازی تبلیغات ادیوری پلاس در اندروید

در این مستند نحوه‌ی استفاده از کتاب‌خانه‌ی تبلیغات ادیوری پلاس در اندروید را شرح می‌دهیم. کتاب‌خانه‌ی ادیوری پلاس امکان نمایش تبلیغات بنری، همسان، میان‌صفحه‌ای و جایزه‌ای را در اپلیکیشن‌های اندروید فراهم می‌کند. با استفاده از این کتاب‌خانه می‌توانید نمایش تبلیغات AdMob اپلیکیشن خود را مدیریت کنید.

حداقل پیش نیاز های ادیوری پلاس

• اندروید استودیو ورژن 4.2 و بالاتر
• گردل ورژن 4.2.2 و بالاتر
• minSdk 16 و بالاتر

افزودن کتاب‌خانه‌ی ادیوری پلاس به پروژه

برای افزودن کتاب‌خانه‌ی ادیوری پلاس ابتدا باید تنظیمات مخزن maven زیر را به فایل build.gradle پروژه یا ماژولی که شامل تنظیمات repositories اپلیکیشن شما است اضافه کنید.

allprojects {

repositories {

google()

/** ریپازیتوری های دیگر */

/** ریپازیتوری مورد نیاز برای ادیوری پلاس */

mavenCentral()

}

}

سپس کتاب‌خانه‌ی ادیوری پلاس را به فایل build.gradle ماژول اپلیکیشن خود اضافه کنید. توصیه می‌کنیم همیشه آخرین نسخه‌ی کتاب‌خانه را استفاده کنید تا از آخرین بهبود‌ها و امکانات بهره‌مند شوید.

dependencies {

/**

* Any other dependencies your module has are placed in this dependency configuration

*/

implementation 'com.adivery:sdk-plus:4.7.3'

}

ادیوری پلاس از نسخه 4.1.0 به بعد به زبان برنامه‌نویسی کاتلین مهاجرت کرده است، بنابراین درصورتی که کاتلین در پروژه شما فعال نیست،این پیش‌نیاز زیر را هم به برنامه خود اضافه کنید.

dependencies {

/**

* Any other dependencies your module has are placed in this dependency configuration

*/

implementation 'com.adivery:sdk-plus:4.7.3'

implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.5.10'

}

کتابخانه‌ی ادیوری پلاس به طور خودکار تنظیمات AndroidManifest.xml و proguard-rules.pro را اضافه می‌کند و نیاز به ایجاد تغییری توسط شما نیست. تنها دسترسی‌ای که به اپلیکیشن شما اضافه خواهد شد، دسترسی استفاده از اینترنت است.

راه اندازی کتابخانه AdMob

برای استفاده از کتابخانه Admob، شما باید حتما از کتابخانه ادیوری پلاس استفاده کنید. سپس کتابخانه Admob را به build.gradle ماژول اپلیکیشن خود اضافه کنید.

dependencies {

/**

* Any other dependencies your module has are placed in this dependency configuration

*/

implementation 'com.google.android.gms:play-services-ads:22.1.0'

}

شما همچنین باید حتما کد زیر را به فایل AndroidManifest.xml اپلیکیشن خود اضافه کنید.

<meta-data

android:name="com.google.android.gms.ads.APPLICATION_ID"

android:value="ca-app-pub-x~y" />

به جای ca-app-pub-x~y شناسه‌ی خود را قرار دهید.

برای تست می توانید از این آیدی استفاده کنید. ca-app-pub-3940256099942544~3347511713

راه اندازی کتاب‌خانه‌ی ادیوری پلاس

ابتدا مطمئن شوید کتاب‌خانه‌ی ادیوری پلاس را در Activity خود import کرده‌اید.

import com.adivery.sdk.*;

سپس در متد onCreate دستور configure را به شکل زیر فرا بخوانید. مقدار APP_ID را با شناسه‌ی اپلیکیشن خود که از داشبورد ناشرین دریافت می‌کنید جایگزین کنید.

@Override

protected void onCreate(Bundle bundle) {

super.onCreate(bundle);

Adivery.configure(getApplication(), APP_ID);

// ... ادامه کد شما

}

تنظیمات مربوط به GDPR

در صورتی که از کتابخانه ادیوری پلاس استفاده می کنید باید حتما متد زیر را در اکتیویتی اصلی برنامه صدا بزنید.

@Override

protected void onCreate(Bundle bundle) {

super.onCreate(bundle);

Adivery.configure(getApplication(), APP_ID);

Adivery.setUpGDPRDialog(yourActivity);

// ... ادامه کد شما

}

تنظیمات proguard

تنظیمات مربوط به proguard در این فایل قرار دارد.

نمایش تبلیغ‌های تمام صفحه

تبلیغات تمام صفحه شامل تبلیغات میان‌صفحه‌ای و جایزه ای می‌شود که در قالب یک صفحه جدید در برنامه شما اجرا شده و تبلیغ‌ها در آن صفحه نمایش داده می‌شوند.

درخواست تبلیغ میان صفحه‌ای

برای درخواست تبلیغ میان ‌صفحه‌ای مشابه نمونه زیر متد prepareInterstitialAd را صدا بزنید و مقدار placementId را با کلید تبلیغ‌گاه خود که در پنل دریافت می‌کنید، جایگزین کنید.

Adivery.prepareInterstitialAd(context, placementId);

هشدار

ادیوری پلاس بطور خودکار پس از نمایش یک تبلیغ، تبلیغ بعدی را برای شما آماده می‌کند و نیازی به فراخوانی دوباره دستور فوق ندارید

درخواست تبلیغ جایزه‌ای

برای درخواست تبلیغ جایزه ای مشابه نمونه زیر متد requestRewardedAd را صدا بزنید و مقدار placementId را با کلید تبلیغ‌گاه خود که در پنل دریافت می‌کنید، جایگزین کنید.

Adivery.prepareRewardedAd(context, placementId);

توجه

ادیوری پلاس بطور خودکار پس از نمایش یک تبلیغ، تبلیغ بعدی را برای شما آماده می‌کند و نیازی به فراخوانی دوباره دستور فوق ندارید

درخواست تبلیغ اجرای اپلیکیشن

برای درخواست تبلیغ اجرای اپلیکیشن (AppOpen) مشابه نمونه زیر متد prepareAppOpenAd را صدا بزنید و PlacementId را با کلید تبلیغ‌گاه خود که از پنل دریافت می‌کنید، جایگزین کنید.

Adivery.prepareAppOpenAd(context, PlacementId);

توجه

ادیوری پلاس بطور خودکار پس از نمایش یک تبلیغ، تبلیغ بعدی را برای شما آماده می‌کند و نیازی به فراخوانی دوباره دستور فوق ندارید

اطلاع از وضعیت تبلیغ‌ها

برای اطلاع از وضعیت بارگذاری و یا نمایش تبلیغ‌ها می‌توانید یک AdiveryListener به Adivery تنظیم کنید.

Adivery.addGlobalListener(new AdiveryListener() {

@Override

public void onAppOpenAdLoaded(String placementId){

// تبلیغ اجرای اپلیکیشن بارگذاری شده است.

}

@Override

public void onInterstitialAdLoaded(String placementId) {

// تبلیغ میان‌صفحه‌ای بارگذاری شده

}

@Override

public void onRewardedAdLoaded(String placementId) {

// تبلیغ جایزه‌ای بارگذاری شده

}

@Override

public void onRewardedAdClosed(String placementId, boolean isRewarded) {

// بررسی کنید که آیا کاربر جایزه دریافت می‌کند یا خیر

}

@Override

public void log(String placementId, String log) {

// پیغام را چاپ کنید

}

});

توجه

listener فوق برای تمام تبلیغ های ‌میان‌صفحه‌ای و جایزه‌ای شما صدا زده می‌شود.

در listener بالا مقدار placementId مشخص کننده تبلیغ‌گاهی است که وضعیت آن تغییر کرده است.

listener بالا شامل توابع زیر نیز می‌باشد که در صورت نیاز می‌توانید آن‌ها را پیاده سازی کنید.

• onError(String placementId, String reason)
• onInterstitialAdLoaded(String placementId)
• onInterstitialAdShown(String placementId)
• onInterstitialAdClicked(String placementId)
• onInterstitialAdClosed(String placementId)
• onRewardedAdLoaded(String placementId)
• onRewardedAdShown(String placementId)
• onRewardedAdClicked(String placementId)
• onRewardedAdClosed(String placementId, boolean isRewarded)
• onAppOpenAdLoaded(String placementId)
• onAppOpenAdShown(String placementId)
• onAppOpenAdClosed(String placementId)
• onAppOpenAdClicked(String placementId)

نمایش تبلیغ

برای نمایش تبلیغ، مشابه زیر متد showAd را صدا بزنید و placementId تبلیغ‌گاه خود را به عنوان ورودی بدهید.

if (Adivery.isLoaded(PlacementId)){

Adivery.showAd(placementId);

}

برای نمایش تبلیغ اجرای اپلیکیشن از دستور زیر استفاده کنید.

if (Adivery.isLoaded(PlacementId)){

Adivery.showAppOpenAd(activity, placementId);

}

توجه

برای نمایش تبلیغ های بعدی در اپلیکیشن خود، تنها لازم است تا دستور فوق را دوباره فراخوانی کنید تا تبلیغ نمایش داده شود.

توجه

به دلیل بار‌گذاری مجدد تبلیغات پس از نمایش، از نمایش تبلیغ در تابع های onAdLoaded خودداری کنید.

بهترین روش برای پیاده سازی تبلیغ اجرای اپلیکیشن

برای نمایش بهینه تبلیغات اجرای اپلیکیشن، ادیوری پلاس پیشنهاد می‌کند برای نمایش تبلیغات، از کد زیر استفاده کنید.

این کد بعد از خروج کاربر از هر نقطه برنامه، در صورتی که کاربر بیش از ۵ ثانیه خارج از اپلیکیشن بماند، تبلیغ اجرای اپلیکیشن را در زمان ورود کاربر، نمایش می‌دهد.

import android.app.Activity;

import android.app.Application;

import android.os.Bundle;

import com.adivery.sdk.Adivery;

import java.util.concurrent.TimeUnit;

class App extends Application implements Application.ActivityLifecycleCallbacks {

@Override

public void onCreate() {

super.onCreate();

registerActivityLifecycleCallbacks(this);

}

private long lastPauseTime = 0L; // or System.currentTimeMills();

@Override

public void onActivityCreated(Activity activity, Bundle savedInstanceState) {

//doing nothing

}

@Override

public void onActivityStarted(Activity activity) {

//doing nothing

}

@Override

public void onActivityResumed(Activity activity) {

long pauseTime = System.currentTimeMillis() - lastPauseTime;

if (pauseTime > TimeUnit.SECONDS.toMillis(5)) {

Adivery.showAppOpenAd(activity, APP_OPEN_PLACEMENT_ID);

}

}

@Override

public void onActivityPaused(Activity activity) {

lastPauseTime = System.currentTimeMillis();

}

@Override

public void onActivityStopped(Activity activity) {

//doing nothing

}

@Override

public void onActivitySaveInstanceState(Activity activity, Bundle outState) {

//doing nothing

}

@Override

public void onActivityDestroyed(Activity activity) {

//doing nothing

}

}

نمایش تبلیغ بنری

برای نمایش تبلیغ بنری در xml مربوط به صفحه اپلیکیشن تکه کد زیر را قرار دهید و مقدار placementId را با کلید تبلیغ‌گاه که در پنل دریافت می‌کنید، جایگزین کنید. همچنین مقدار bannerType را با توجه به تبلیغ‌گاه ایجاد شده، کامل کنید.

<com.adivery.sdk.AdiveryBannerAdView

android:layout_width="match_parent"

android:layout_height="wrap_content"

android:id="@+id/banner_ad"

app:placement_id="placementId"

app:banner_size="banner"/>

مقادیر ممکن برای BANNER_TYPE با توجه به نوع تبلیغ‌گاه تعریف شده در داشبورد ناشرین:

• بنر سایز ۵۰×۳۲۰: BannerType.BANNER یا banner
• بنر سایز ۱۰۰×۳۲۰: BannerType.LARGE_BANNER یا large_banner
• بنر سایز ۲۵۰×۳۰۰: BannerType.MEDIUM_RECTANGLE یا medium_rectangle
• بنر سایز ۳۲۰×۵۰ یا ۳۲۰×۹۰ : BannerType.SMART_BANNER یا smart_banner

درصورتی که می‌خواهید بدون استفاده از xml تبلیغ را بارگذاری کنید، میتوانید یک آبجکت از کلاس AdiveryBannerAdView ساخته و مقادیر را بصورت دستی تنظیم کنید.

نمایش تبلیغ بنری

برای نمایش تبلیغ بنری می‌توانید از کدی مشابه کد زیر استفاده کنید.

AdiveryBannerAdView bannerAd = findViewById(R.id.banner_ad);

bannerAd.setBannerAdListener(new AdiveryAdListener() {

@Override

public void onAdLoaded() {

// تبلیغ به‌طور خودکار نمایش داده می‌شود، هر کار دیگری لازم است اینجا انجام دهید.

}

@Override

public void onError(String reason){

// خطا را چاپ کنید تا از دلیل آن مطلع شوید

}

@Override

public void onAdClicked(){

// کاربر روی بنر کلیک کرده

}

});

bannerAd.loadAd();

نمایش تبلیغ همسان

برای پیاده‌سازی تبلیغ همسان می‌توانید از کلاس AdiveryNativeAdView مشابه نمونه‌ی زیر استفاده کنید.

<com.adivery.sdk.AdiveryNativeAdView

android:id="@+id/native_ad_view"

android:layout_width="wrap_content"

android:layout_height="wrap_content"

app:placement_id="placementId"

app:adivery_native_ad_layout="@layout/ad_layout_example" />

مشخصه‌ی placement_id نشان دهنده کلید تبلیغ‌گاه شماست و باید مقدار آن‌را از پنل کاربری دریافت کنید.

مشخصه‌ی adivery_native_ad_layout نشان دهنده‌ی layout تبلیغ همسان شماست. یک نمونه از layout همسان را در زیر می‌بینید.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"

android:layout_width="300dp"

android:layout_height="wrap_content"

android:orientation="vertical">

<com.adivery.sdk.AdiveryNativeAdMediaView

android:id="@+id/adivery_image"

android:layout_width="300dp"

android:layout_height="wrap_content"

android:adjustViewBounds="true"

android:scaleType="centerCrop" />

<LinearLayout

android:layout_width="match_parent"

android:layout_height="wrap_content"

android:gravity="center_vertical"

android:orientation="horizontal"

android:padding="4dp">

<Button

android:id="@+id/adivery_call_to_action"

android:layout_width="wrap_content"

android:layout_height="wrap_content"

android:layout_margin="4dp" />

<TextView

android:id="@+id/adivery_headline"

android:layout_width="0dp"

android:layout_height="wrap_content"

android:layout_margin="4dp"

android:layout_weight="1" />

<ImageView

android:id="@id/adivery_icon"

android:layout_width="36dp"

android:layout_height="36dp"

android:layout_margin="4dp" />

</LinearLayout>

</LinearLayout>

هر تبلیغ همسان از المان‌های متنی و تصویری به همراه یک دکمه‌ی فراخوان تشکیل شده است. از میان المان‌های زیر نمایش عنوان تبلیغ و دکمه‌ی فراخوان اجباری است.

• المان TextView با شناسه‌ی @+id/adivery_headline که عنوان تبلیغ است.
• المان TextView با شناسه‌ی @+id/adivery_description که توضیحات تبلیغ است.
• المان TextView با شناسه‌ی @+id/adivery_advertiser که نام برند یا اپلیکیشن مورد تبلیغ است.
• المان Button با شناسه‌ی @+id/adivery_call_to_action که دکمه‌ی فراخوان تبلیغ است.
• المان AdiveryNativeAdMediaView با شناسه‌ی @+id/adivery_image که عکس سایز بزرگ تبلیغ است با نسبت ابعاد 16:9 و جهت افقی.
• المان ImageView با شناسه‌ی @+id/adivery_icon که آیکون برند یا اپلیکیشن مورد تبلیغ است. این عکس در ابعاد کوچک و به شکل مربع خواهد بود. همچنین ممکن است بخش‌هایی از عکس transparent باشد.

پس از طراحی layout و اتصال آن به AdiveryNativeAdView به صورت زیر می‌توانید درخواست تبلیغ همسان را بدهید و نمایش دهید:

AdiveryNativeAdView adView = findViewById(R.id.native_ad_view);

adView.setListener(new AdiveryAdListener() {

@Override

public void onAdLoaded() {

// تبلیغ شما بارگذاری شد

}

@Override

public void onError(reason: String) {

// خطا را لاگ کنید تا از دلیل آن باخبر شوید.

}

@Override

public void onAdShown() {

// تبلیغ نمایش داده شد

}

@Override

public void onAdClicked() {

// کاربر روی تبلیغ کلیک کرد

}

});

adView.loadAd();

رفع مشکلات

ممکن است به دلایلی موفق به نمایش تبلیغات نشوید. برای بررسی جزئیات مساله می‌توانید لاگ‌های کتاب‌خانه‌ی ادیوری پلاس و دیگر کتاب‌خانه‌های متصل شده را با فراخوانی دستور زیر فعال کنید و در کنسول لاگ اپلیکیشن خود جزئیات بیشتری در مورد علت بروز مشکل بخوانید.

Adivery.setLoggingEnabled(true);