رفتن به مطلب اصلی
Version: 4.x.x

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

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

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

  • اندروید استودیو ورژن 4.2 و بالاتر
  • گردل ورژن 4 و بالاتر
  • 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:4.1.4'
}

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

dependencies {
/**
* Any other dependencies your module has are placed in this dependency configuration
*/
implementation 'com.adivery:sdk:4.1.4'
implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.5.10'
}

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

راه اندازی کتاب‌خانه‌ی ادیوری#

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

import com.adivery.sdk.*;

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

@Override
protected void onCreate(Bundle bundle) {
super.onCreate(bundle);
Adivery.configure(getApplication(), APP_ID);
// ... ادامه کد شما
}

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

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

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

برای درخواست تبلیغ میان ‌صفحه‌ای مشابه نمونه زیر متد requestInterstitialAd را صدا بزنید و مقدار 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 خودداری کنید.

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

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

<com.adivery.sdk.AdiveryBannerAdView
android:layout_width="match_parent"
android:layout_height="wrap_content"
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);