Implementazione nativa di AFS per Android

L'SDK Google Mobile Ads supporta anche gli stili personalizzati degli annunci associati ai risultati di ricerca. Se la tua app utilizza già l'SDK Google Mobile Ads, ti consigliamo di usare l'SDK AFSMA.

Se esegui l'upgrade alla versione 19.0.0 o successiva dalla 18.1.0 o precedenti, consulta la nostra guida alla migrazione.

Prerequisiti

Questa guida all'implementazione presume che tu abbia familiarità con:

Importa l'SDK nativo AFS

Aggiungi l'SDK

Per aggiungere l'SDK nativo AFS alla tua app:

Apri il file build.gradle all'interno della directory del modulo dell'applicazione. Aggiungi una nuova regola di build in dependencies per l'ultima versione dell'SDK:

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

Assicurati che il tuo build.gradle di primo livello contenga un riferimento al repository google() o al maven { url "https://maven.google.com" }.

Segui queste istruzioni per includere il plug-in della versione autonoma di Google Play nel tuo progetto. L'applicazione di questo plug-in causa un errore di build gradle quando l'SDK nativo AFS viene utilizzato con una versione incompatibile di Google Play Services invece di consentire la creazione dell'app, ma potrebbe causare arresti anomali del runtime. Oppure applica la failOnVersionConflict() StrategyStrategy al tuo progetto per causare un errore di build quando nel progetto vengono utilizzate versioni incompatibili di Google Play Services. Salva le modifiche e fai clic su Sincronizza progetto con file Gradle nella barra degli strumenti.

Usare AndroidX anziché le Librerie di assistenza Android

A partire dalla versione 17.0.0 dell'SDK, l'app deve utilizzare le librerie Jetpack (AndroidX) anziché le Android Support Libraries. Requisiti di compatibilità:

  • Imposta com.android.tools.build:gradle su v3.2.1 o versioni successive.
  • Imposta compileSdkVersion su 28 o versioni successive.
  • Aggiorna l'app per utilizzare Jetpack (AndroidX); segui le istruzioni nella sezione Migrazione ad AndroidX.

Corsi

Per pubblicare annunci nativi AFS nella tua app, implementa le seguenti classi:

SearchAdController

  • Questa classe è responsabile della richiesta asincrona degli annunci, della memorizzazione nella cache e del recupero degli annunci e del rendering degli annunci.
  • Ogni contesto dell'annuncio richiede un elemento SearchAdController separato; ad esempio, se hai una schermata che mostra gli annunci accanto a un elenco di risultati di ricerca e un'altra schermata che mostra gli annunci con i dettagli per un prodotto specifico, devi creare due istanze separate di SearchAdController, una per ogni caso.
  • Il costruttore deve fornire il codice proprietà web (ID publisher), l'ID stile da applicare agli annunci restituiti e SearchAdOptions. L'elemento Context fornito nel costruttore deve essere l'elemento Activity che contiene SearchAdController e l'annuncio View in cui verrà inserito l'annuncio.
  • Chiama loadAds per indicare una nuova ricerca dell'utente e avviare una richiesta di annuncio asincrono. Tutti gli annunci caricati dalle chiamate precedenti a loadAds vengono cancellati dalla cache degli annunci interna quando viene effettuata una nuova chiamata.
  • Crea un View con createAdView per visualizzare le creatività degli annunci.
  • Una volta caricati gli annunci, chiama populateAdView con un View precedentemente generato con createAdView per eseguire il rendering di un annuncio memorizzato nella cache in tale View. Oltre al View da compilare, fornisci un adKey, una stringa arbitraria per identificare in modo univoco l'annuncio. In questo modo viene associata la creatività dell'annuncio specifica restituita dalla cache con il tag adKey, quindi quando lo stesso adKey viene passato a una chiamata futura a populateAdView, verrà restituito lo stesso annuncio. Ad esempio, se populateAdView viene chiamato per la prima volta con adKey="keyA" e viene visualizzato un annuncio per le scarpe da trekking, ogni chiamata successiva a populateAdView con adKey="keyA" verrà completata per lo stesso annuncio per le scarpe da trekking. (Dopo aver effettuato una nuova chiamata a loadAds, verranno cancellati tutti gli annunci memorizzati nella cache e le chiavi degli annunci associate).

SearchAdOptions

  • Passa questo oggetto al costruttore SearchAdController per personalizzare il modo in cui vengono richiesti e visualizzati gli annunci. Chiama build() su un SearchAdOptions.Builder per creare un oggetto SearchAdOptions.

View

  • Crea un oggetto View per bloccare gli annunci chiamando createAdView() su SearchAdController. Mostra al massimo un annuncio alla volta, ma lo stesso View può essere riciclato per mostrare annunci diversi nel tempo.

SearchAdRequest

  • Chiama il metodo loadAds su SearchAdController con SearchAdRequest per avviare una richiesta di annuncio asincrona. Chiama build() su un SearchAdRequest.Builder per creare un oggetto SearchAdRequest.

AdListener

  • Implementa questa interfaccia e passala al costruttore SearchAdController per registrare i callback per diversi stati.
  • Nota: AdListener callback non verranno chiamati in seguito a una richiesta annullata (chiamata a loadAds prerilasciata da un'altra chiamata a loadAds prima della risoluzione della prima chiamata).

Esempio di implementazione

L'esempio seguente mostra la creazione di un elemento SearchAdController in un esempio 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);
}

Quando l'utente avvia una query, crea un SearchAdRequest e chiama loadAds su SearchAdController per avviare una richiesta di annuncio asincrona.

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

Implementa il callback onAdLoaded per completare un annuncio caricato in una visualizzazione dell'annuncio.

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");
}

Un annuncio correlato alla query verrà visualizzato nel adView.

Analisi degli errori

SearchAdController richiede un oggetto AdListener con il metodo onAdLoaded() per comunicare all'app che gli annunci sono pronti per essere visualizzati. Devi anche implementare il metodo onAdFailedToLoad() per rilevare e correggere gli errori. Ad esempio, potresti utilizzare il seguente AdListener per eseguire il debug dell'implementazione:

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);
    }
};

Le costanti utilizzate nel metodo di callback onAdFailedToLoad() sono definite in Ad Locator.