AFS Native Implementation برای اندروید

Google Mobile Ads SDK همچنین از سبک های جستجوی سفارشی پشتیبانی می کند. اگر برنامه شما قبلاً از Google Mobile Ads SDK استفاده می‌کند، توصیه می‌کنیم به جای آن از نسخه AFSMA SDK استفاده کنید.

اگر از نسخه 18.1.0 یا جدیدتر به نسخه 19.0.0 یا بالاتر ارتقا می دهید، لطفاً راهنمای مهاجرت ما را ببینید.

پیش نیازها

این راهنمای پیاده سازی فرض می کند که شما با موارد زیر آشنا هستید:

AFS Native SDK را وارد کنید

SDK را اضافه کنید

برای افزودن AFS Native SDK به برنامه خود، موارد زیر را انجام دهید:

فایل build.gradle را در دایرکتوری ماژول برنامه خود باز کنید. یک قانون ساخت جدید تحت dependencies برای آخرین نسخه SDK اضافه کنید:

dependencies {
  implementation 'com.google.android.gms:play-services-afs-native:19.0.3'
}

مطمئن شوید که build.gradle سطح بالای شما حاوی ارجاعی به مخزن google() یا maven { url "https://maven.google.com" } .

این دستورالعمل ها را دنبال کنید تا افزونه Google Play Standalone Version Matcher را در پروژه خود بگنجانید. زمانی که AFS Native SDK با نسخه ناسازگار Google Play Services استفاده می‌شود، به‌جای اینکه به برنامه اجازه ساخت بدهد، اما به‌طور بالقوه باعث خرابی‌های زمان اجرا شود، استفاده از این افزونه باعث ایجاد خطای gradle build می‌شود. یا، failOnVersionConflict() ResolutionStrategy را در پروژه خود اعمال کنید تا زمانی که از نسخه های ناسازگار سرویس های Google Play در پروژه شما استفاده می شود، خطای ساخت ایجاد شود. تغییرات را ذخیره کنید و روی Sync Project with Gradle Files در نوار ابزار کلیک کنید.

از AndroidX به جای کتابخانه های پشتیبانی اندروید استفاده کنید

با شروع نسخه 17.0.0 SDK، برنامه شما باید از کتابخانه‌های Jetpack (AndroidX) به جای کتابخانه‌های پشتیبانی Android استفاده کند. الزامات سازگاری:

  • com.android.tools.build:gradle را روی نسخه 3.2.1 یا جدیدتر تنظیم کنید.
  • compileSdkVersion را روی 28 یا بالاتر تنظیم کنید.
  • برنامه خود را برای استفاده از Jetpack (AndroidX) به روز کنید. دستورالعمل‌های انتقال به AndroidX را دنبال کنید.

کلاس ها

برای ارائه تبلیغات بومی AFS در برنامه خود، کلاس های زیر را اجرا کنید:

SearchAdController

  • این کلاس مسئول درخواست تبلیغات ناهمزمان، ذخیره و بازیابی تبلیغات و رندر تبلیغات است.
  • هر زمینه تبلیغاتی به یک SearchAdController جداگانه نیاز دارد. به عنوان مثال، اگر صفحه‌ای دارید که تبلیغات را در کنار فهرستی از نتایج جستجو نشان می‌دهد و صفحه دیگری که تبلیغات را در کنار جزئیات یک محصول خاص نشان می‌دهد، باید دو نمونه جداگانه از SearchAdController ایجاد کنید، یکی برای هر مورد.
  • سازنده باید کد دارایی وب شما (شناسه ناشر)، شناسه سبک برای اعمال در تبلیغات برگشتی و SearchAdOptions را ارائه کند. Context ارائه شده در سازنده باید Activity باشد که حاوی SearchAdController و جایی است که View تبلیغ را در آن قرار می دهید.
  • با loadAds تماس بگیرید تا جستجوی کاربر جدید را نشان دهید و درخواست تبلیغات ناهمزمان را آغاز کنید. هر آگهی بارگیری شده از تماس های قبلی با loadAds ، هنگام برقراری تماس جدید، از حافظه پنهان تبلیغات داخلی پاک می شود.
  • برای نمایش خلاقیت های تبلیغاتی، یک View با createAdView ایجاد کنید.
  • پس از بارگیری تبلیغات، با یک View که قبلاً با createAdView ایجاد شده بود، با populateAdView تماس بگیرید تا یک تبلیغ ذخیره شده در حافظه پنهان در آن View ارائه شود. علاوه بر View که قرار است پر شود، یک adKey ، یک رشته دلخواه برای شناسایی منحصر به فرد آگهی ارائه دهید. این آگهی تبلیغاتی خاص بازگردانده شده از حافظه پنهان را با آن adKey مرتبط می‌کند، بنابراین وقتی همان adKey به یک فراخوان آینده به populateAdView ارسال می‌شود، همان آگهی بازگردانده می‌شود. برای مثال، اگر populateAdView برای اولین بار با adKey="keyA" فراخوانی شود و تبلیغی برای کفش های پیاده روی ارائه کند، هر تماس بعدی با populateAdView با adKey="keyA" همان تبلیغ را برای کفش های پیاده روی پر می کند. (با برقراری تماس جدید با loadAds همه تبلیغات ذخیره شده در حافظه پنهان و کلیدهای تبلیغات مرتبط پاک می شوند.)

SearchAdOptions

  • این شی را به سازنده SearchAdController ارسال کنید تا نحوه درخواست و نمایش تبلیغات را سفارشی کنید. برای ایجاد یک شی SearchAdOptions build() را در SearchAdOptions.Builder فراخوانی کنید.

View

  • با فراخوانی createAdView() در SearchAdController ، یک شی View برای نگهداری تبلیغات ایجاد کنید. حداکثر یک آگهی را در یک زمان نمایش می دهد، اما همان View می توان برای نمایش تبلیغات مختلف در طول زمان بازیافت کرد.

SearchAdRequest

  • روش loadAds را در SearchAdController با SearchAdRequest فراخوانی کنید تا یک درخواست تبلیغات ناهمزمان آغاز شود. برای ایجاد یک شی SearchAdRequest build() را در SearchAdRequest.Builder فراخوانی کنید.

AdListener

  • این رابط را پیاده سازی کنید و آن را به سازنده SearchAdController ارسال کنید تا تماس های چند حالته را ثبت کند.
  • توجه: در صورت درخواست لغو شده، تماس‌های AdListener فراخوانی نمی‌شوند (تماسی با loadAds که قبل از حل شدن اولین تماس توسط تماس دیگری با loadAds انجام شده است).

اجرای نمونه

مثال زیر ایجاد SearchAdController در یک نمونه Activity نشان می دهد.

//  MainActivity.java implementation
//  (MainActivity is a subclass of Activity)

SearchAdController adController;
// adContainer where we will place our ads in this example.
ViewGroup adContainer;

protected void onCreate(Bundle bundle){
  super.onCreate(bundle);
  adContainer = (ViewGroup) findViewById(...);
  // Specify ad options (not required).
  SearchAdOptions.Builder adOptionsBuilder = new SearchAdOptions.Builder();
  adOptionsBuilder.setAdType(SearchAdOptions.AD_TYPE_TEXT);
  adOptionsBuilder.setPrefetch(true);
  adOptionsBuilder.setNumAdsRequested(3);
  // Provide a callback to trigger when ads are loaded.
  AdListener adListener = new AdListener() {
    public void onAdLoaded() {
      createAndShowAd();
    }
  };
  // Instantiate the SearchAdController.
  adController = new SearchAdController(this, "your-client-id", "your-style-id",
                                        adOptionsBuilder.build(), adListener);
}

هنگامی که کاربر یک پرس و جو را آغاز می کند، یک SearchAdRequest ایجاد کنید و loadAds در SearchAdController فراخوانی کنید تا یک درخواست تبلیغات ناهمزمان شروع شود.

// Create the request.
SearchAdRequest.Builder requestBuilder = new SearchAdRequest.Builder();
requestBuilder.setQuery("user query here");
// Load the ads.
adController.loadAds(requestBuilder.build());

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

private void createAndShowAd() {
  // Create a new view that will contain the ad.
  View adView = adController.createAdView();
  // Attach the new view to the view hierarchy.
  adContainer.addView(adView);
  // Display the ad inside the adView. We need to provide an adKey to
  // indicate which ad is to be displayed in the adView. In this example, 
  // since we only have one ad, we can provide any constant string. However, 
  // if you intend to display multiple ads, each ad you wish to display
  // should be given a unique adKey of your choosing.
  adController.populateAdView(adView, "demoAd");
}

اکنون یک تبلیغ مرتبط با درخواست داده شده در adView ظاهر می شود.

بررسی خطاها

SearchAdController به یک شی AdListener با روش onAdLoaded() نیاز دارد تا به برنامه شما اطلاع دهد که تبلیغات آماده نمایش هستند. همچنین باید متد onAdFailedToLoad() را پیاده سازی کنید تا بتوانید خطاها را شناسایی و تصحیح کنید. به عنوان مثال، ممکن است از AdListener زیر برای رفع اشکال پیاده سازی خود استفاده کنید:

AdListener adListener = new AdListener() {
    public void onAdLoaded() {
        // Called when an ad is loaded.
        Toast.makeText(MainActivity.this, "Ad Loaded",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example).
        Toast.makeText(MainActivity.this, "Ad Left Application",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
    }

    @Override
    public void onAdFailedToLoad(int errorCode) {
        // Called when an ad request failed.
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
};

ثابت‌های مورد استفاده در متد onAdFailedToLoad() در AdListener تعریف شده‌اند.