[AD.AGIO] ANDROID SDK

[AD.AGIO] ANDROID SDK 2013.06 Pag. 1

1. PREMESSA Il presente documento riporta informazioni riservate il cui utilizzo è confidenziale e permesso esclusivamente nell'ambito del rapporto di fornitura in atto. 2. INTRODUZIONE AdAgioSDK è una SDK per la gestione degli ads erogati dalla piattaforma [ad.agio] di Neodata Group, finalizzata ad integrare nella maniera più semplice possibile la logica di gestione degli ads direttamente all interno delle applicazioni Android, in maniera trasparente per gli sviluppatori delle applicazioni. Il presente manuale intende illustrare le operazioni di setup del progetto e le chiamate necessarie all integrazione dei banner pubblicitari delle proprie applicazioni da parte dei developer. 3. FORMATI La libreria AdAgioSDK è in grado di gestire banner standard ed interstitial, come da specifiche IAB MRAID (www.iab.net/mraid). Il banner standard è una strip statica cliccabile di dimensioni 320x50. Il click sul banner consente la visualizzazione della landing page su una nuova istanza del browser di sistema o su minibrowser modale. E possibile gestire rich-media di tipo espandibile, ovvero un banner con dimensioni iniziali standard, che si espande al click dell utente. La gestione dell espansione è totalmente a carico della SDK, ed equivale all apertura di un layer full-screen opportunamente provvisto di un bottone per la chiusura. Alla pressione sul tasto di chiusura il banner ritorna di dimensioni ridotte. 2 / 13

Il banner di tipo interstitial viene visualizzato su un layer full-screen espanso, provvisto di tasto per la chiusura. Il banner interstitial dovrà essere istanziato con dimensioni di partenza 1x1. Dopo la sua chiusura il banner non sarà più visibile. Il click sul banner permetterà la visualizzazione della landing page su una nuova istanza del browser di sistema o su minibrowser modale. 4. REFRESH DEL BANNER La libreria consente di impostare un tempo di refresh, per consentire l aggiornamento automatico del banner da visualizzare attraverso il metodo setrefreshrate(int refreshrate. L intero refreshrate indica il numero di secondi. Impostando zero (0) i banner non saranno mai aggiornati automaticamente. 5. MINIBROWSER MODALE Per l apertura della landing page al click sul banner, per evitare di perdere il focus della propria applicazione, AdAgioSDK incorpora un sistema di navigazione interna su finestra modale. Per utilizzarlo è necessario impostare la proprietà usemodalbrowser(true) sull oggetto banner. Diversamente le pagine verranno aperte su browser nativo esterno. 6. GESTIONE OFFLINE L SDK gestisce l assenza di connessione nei seguenti modi: 1. Se la rete manca sin da subito, non sarà mostrato alcun banner e verrà notificato il fallimento scatenando l evento onadfailure. Il banner verrà visualizzato non appena sarà fatta una nuova chiamata in presenza di connettività. 2. Se è stato impostato un tempo di refresh e al momento del refresh la rete manca, continuerà ad essere visualizzato l ultimo banner correttamente caricato, finché non sarà possibile effettuare un nuovo refresh. 3 / 13

Per ogni refresh in assenza di connettività verrà sempre notificato l evento onadfailure e non sarà mostrato alcun banner. 7. SETUP DEL PROGETTO ANDROID/ECLIPSE 7.1. IMPORTAZIONE DELLA LIBRERIA NEL PROGETTO Trasferire la libreria AdAgioSDK.jar sul proprio PC. Creare un folder libs nel progetto Eclipse/Android e copiarvi dentro il file AdAgioSDK.jar. Su Eclipse, cliccare col tasto destro sul progetto, selezionare Build Path, Configure Build Path. Cliccare sul tab Libraries, quindi Add Jars..., sfogliare le directory fino alla libs e selezionare AdAgioSDK Cliccare sul tab Order and export, quindi spuntare la casella relativa alla libreria AdAgioSDK.jar Da questo momento le classi incluse nella libreria saranno disponibili per Eclipse sia in fase di compilazione del progetto che di auto completamento del codice durante l editing. 7.2. IMPOSTAZIONE DEL MANIFEST Il file AndroidManifest.xml deve essere modificato al fine di includere, subito prima del tag application, le seguenti istruzioni per consentire l accesso alla rete: <uses-permission android:name="android.permission.access_network_state" /> <uses-permission android:name="android.permission.internet" /> <uses-permission android:name="android.permission.read_phone_state" /> Per abilitare il servizio di geo-localizzazione dei banner è necessario inserire anche i seguenti permessi: 4 / 13

<uses-permission android:name="android.permission.access_coarse_location"/> <uses-permission android:name="android.permission.access_fine_location"/> Il servizio di georeferenziazione è tuttavia opzionale e la libreria fornisce dei metodi per disabilitare l inoltro delle coordinate geografiche anche in presenza dei relativi permessi sul manifest. All interno dell elemento application, occorre dichiarare il seguente servizio: <service android:name="com.neodata.adagiosdk.communicationmanagerservice"/> e abilitare l accelerazione hardware per consentire la corretta riproduzione di video banner: android:hardwareaccelerated="true" Infine, affinché un evento di rotazione del device o di apertura della tastiera fisica non causi la distruzione dell activity con conseguente duplicazione delle richieste di ad, occorre specificare dentro il tag activity l attributo: android:configchanges="orientation keyboardhidden screensize" 5 / 13

7.3. ESEMPIO COMPLETO DI ANDROIDMANIFEST.XML <?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.neodata.adagiosdktest" android:versioncode="1"android:versionname="1.0" > <uses-sdk android:minsdkversion="8" android:targetsdkversion="17"/> <uses-permission android:name="android.permission.access_network_state" /> <uses-permission android:name="android.permission.internet" /> <uses-permission android:name="android.permission.read_phone_state" /> <uses-permission android:name="android.permission.access_coarse_location"/> <uses-permission android:name="android.permission.access_fine_location"/> <application android:icon="@drawable/ic_launcher" android:label="@string/app_name" android:hardwareaccelerated="true"> <service android:name = "com.neodata.adagiosdk.communicationmanagerservice"/> <activity android:name=".adagiosdktestactivity" android:configchanges="orientation keyboardhidden screensize" android:label="@string/app_name" > <intent-filter> <action android:name="android.intent.action.main" /> <category android:name="android.intent.category.launcher" /> </intent-filter> </activity> </application> </manifest> 6 / 13

8. API DI ADAGIOUTILS void disablelocationpermanently() inibisce globalmente e permanentemente la geo localizzazione API DI ADAGIOADV AdAgioADV( Activity activity, AdAgioADView adview) Costruttore AdAgioADV(Activity activity, int viewid) Costruttore AdAgioADV(Activity activity, int viewid, String clientid, String positionid) Costruttore AdAgioADV(Activity activity, AdAgioADView adview, String clientid, String positionid) Costruttore void setclientid(string clientid) setta il clientid (comunicato da Neodata) void setpositionid(string position) setta l identificativo della posizione dell ad (comunicato da Neodata) void setrefreshrate(int refreshrate) void disablelocation() setta l intervallo di tempo (in secondi) tra un refresh e il successivo. refreshrate= 0 disabilita il refresh automatico del banner disabilita la geolocalizzazione per questo ad 7 / 13

void setkw(string keywords) setta delle keyword separate da pipe ( ) (opzionale) void addadlistener(adagioadlistener adlistener) Assegna un AdAgioAdListener a questo ad void usemodalbrowser(boolean usemodal) Setta l utilizzo del browser modale per l apertura della landing page. - true: viene utilizzato un mini browser modale interno. - false: viene utilizzato il browser nativo. void loadadv() void loadinterstitial() Effettua la richiesta di caricamento del banner Effettua la richiesta di caricamento del banner interstitial API DI ADAGIOADVIEW AdAgioADV(Context context) AdAgioADV(Context context, AdvBannerSize adsize) Costruttore Costruttore API DI ADVBANNERSIZE AdvBannerSize.BANNER Fissa le dimensioni default per il Banner: width:320dp ed height: 50dp AdvBannerSize.INTERSTITIAL Fissa le dimensioni default per 8 / 13

l Interstitial: width:1dp ed height: 1dp API DELL INTERFACCIA ADAGIOADLISTENER void onadreceived() void onadfailure() void onclick() Notifica la corretta ricezione dell ad Fallimento nella procedura di caricamento dell ad, dovuto ad un problema di rete, errore di configurazione o assenza di banner da mostrare. Notifica dell avvenuto click sul banner 9. UTILIZZO IN FASE DI SVILUPPO 9.1. INSERIMENTO DELLE VIEW NEI LAYOUT Per poter integrare all interno di una Activity una finestra AdAgioADView per la visualizzazione di banner pubblicitari è necessario inserire una view del tipo com.neodata.adagiosdk.adagioadview all interno del layout (tramite file XML o programmaticamente). Tale view supporta tutti gli attributi tipici di una WebView, oltre a quelli comuni a tutte le View. E possibile inserire più di una AdAgioADView in ogni layout, con l ovvia accortezza di differenziarne l id. Le dimensioni tipiche per i banner standard sono 320x50, mentre l interstitial va settato con dimensioni di partenza 1x1. ESEMPIO 1. ADAGIOADVIEW BANNER TRAMITE XML <com.neodata.adagiosdk.adagioadview android:id="@+id/mybanner" 9 / 13

android:layout_width="320dp" android:layout_height="50dp" android:layout_alignparenttop="true" android:layout_centerhorizontal="true" /> ESEMPIO 2. ADAGIOADVIEW INTERSTITIAL TRAMITE XML <com.neodata.adagiosdk.adagioadview android:id="@+id/myinterstitial" android:layout_width="1dp" android:layout_height="1dp"/> 9.2. RICHIEDERE UN BANNER Per richiedere un banner occorre istanziare un oggetto della classe AdAgioADV, settare tutti i parametri obbligatori e chiamare il metodo: loadadv() per i banner o loadinterstitial()in caso di interstitial. I parametri obbligatori sono: - activity: activity che richiede il banner - adview: risorsa rappresentante la view AdAgioADView o il relativo identificativo (istanziato nel file XML di layout) - clientid: parametro comunicato da Neodata - positionid: parametro comunicato da Neodata ESEMPIO 3. ISTANZA DI ADAGIOADV PER BANNER CREATO TRAMITE LAYOUT XML // Creazione di una istanza di AdAgioADV: 10 / 13

AdAgioADV advertising = new AdAgioADV(this, R.id.myBanner); // Impostazione del ClientId, comunicato off band da Neodata: advertising.setclientid(neodata_client_id); // Impostazione del PositionID, comunicato off band da Neodata: advertising.setpositionid(neodata_position_id); // Impostazione delle keywords: advertising.setkw("these are example keywords"); //Impostazione AdAgioADListener per l ad advertising.addadlistener(new AdAgioADListener(){ public void onadfailure() { Log.d("TEST","@@@@@@@@ Chiamato metodo onadfailure"); public void onadreceived() { Log.d("TEST","@@@@@@@@ Chiamato metodo onadreceived"); public void onclick() { Log.d("TEST","@@@@@@@@ Chiamato metodo onclick"); ); try { advertising.loadadv(); catch (Exception e) { Log.d("TEST", e.tostring()); 11 / 13

ESEMPIO 4. ISTANZA DI ADAGIOADV PER INTERTITIAL CREATO PROGRAMMATICAMENTE //Creazione istanza AdAgioADView AdAgioADView adinterstitial = new AdAgioADView(this,AdvBannerSize.INTERSTITIAL); //Aggiunta oggetto AdAgioADView al layout LinearLayout layout = (LinearLayout)findViewById(R.id.layout); layout.addview(adinterstitial); //Creazione istanza AdAgioADV attraverso i parametri inviati off band da Neodata (sintassi compatta) AdAgioADV advertising = new AdAgioADV(this, adinterstitial, NEODATA_CLIENT_ID, NEODATA_POSITION_ID); // Impostazione delle keywords: advertising.setkw("these are example keywords"); //Impostazione AdAgioADListener per l ad advertising.addadlistener(new MyAdListener()); try { advertising.loadadv(); catch (Exception e) { Log.d("TEST", e.tostring()); 9.3. IMPLEMENTAZIONE DELL INTERFACCIA ADAGIOADLISTENER Implementando l interfaccia AdAgioADListener è possibile ottenere informazioni sull esito del caricamento del banner e sugli eventuali click in esso. 12 / 13

ESEMPIO IMPLEMENTAZIONE ADAGIOADLISTENER import com.neodata.adagiosdk.adagioadlistener; import android.util.log; public class MyAdListener implements AdAgioADListener { public void onadfailure() { Log.d("TEST","@@@@@@@@ Chiamato metodo onadfailure"); public void onadreceived() { Log.d("TEST","@@@@@@@@ Chiamato metodo onadreceived"); public void onclick() { Log.d("TEST","@@@@@@@@ Chiamato metodo onclick"); 13 / 13