WINDOWS PHONE SDK V.1.0

Transcript

1 [AD.AGIO] WINDOWS PHONE SDK V.1.0 OTTOBRE 2013 Pag. 1

2 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 Windows Phone, 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. SETUP DEL PROGETTO WINDOWS PHONE/VISUAL STUDIO 3.1. IMPORTAZIONE DELLA LIBRERIA NEL PROGETTO Trasferire la libreria AdAgioSDK.dll sul proprio PC. Su Visual Studio, andare su Esplora soluzioni, cliccare col tasto destro sulla cartella Riferimenti del progetto, selezionare Aggiungi riferimento... Cliccare sul tab Sfoglia e selezionare AdAgioSDK.dll. Da questo momento le classi incluse nella libreria saranno disponibili per Visual Studio sia in fase di compilazione del progetto che di auto completamento del codice durante l editing IMPOSTAZIONE DEL MANIFEST Il file WMAppManifest.xml deve essere modificato al fine di includere, subito prima dell elemento App, le seguenti istruzioni per consentire l accesso alla rete: <Capabilities> <Capability Name="ID_CAP_WEBBROWSERCOMPONENT" /> <Capability Name="ID_CAP_IDENTITY_DEVICE" /> <Capability Name="ID_CAP_NETWORKING" /> Neodata Group srl Viale Vittorio Veneto 42 - Catania T / 9

3 <Capability Name="ID_CAP_PHONEDIALER" /> </Capabilities> Per consentire la geo localizzazione è necessario abilitare i seguenti permessi: <Capability Name="ID_CAP_LOCATION" /> 3.3. ESEMPIO COMPLETO DI WMAPPMANIFEST.XML <?xml version="1.0" encoding="utf-8"?> <Deployment xmlns=" AppPlatformVersion="7.1"> <App xmlns="" ProductID="f2fcd6d4-39ad-46cb-a278-6f03c62e15e9" Title="NeodataTestApp" RuntimeType="Silverlight" Version=" " Genre="apps.normal" Author="Neodata Team" Description="Neodata SDK TestApp" Publisher="Neodata Group s.r.l." BitsPerPixel="32"> <IconPath IsRelative="true" IsResource="false">ApplicationIcon.png</IconPath> <Capabilities> <Capability Name="ID_CAP_WEBBROWSERCOMPONENT" /> <Capability Name="ID_CAP_IDENTITY_DEVICE" /> <Capability Name="ID_CAP_NETWORKING" /> <Capability Name="ID_CAP_PHONEDIALER" /> <Capability Name="ID_CAP_LOCATION" /> </Capabilities> <Tasks> <DefaultTask Name="_default" NavigationPage="MainPage.xaml" /> </Tasks> <Tokens> <PrimaryToken TokenID="NeodataTestAppToken" TaskName="_default"> <TemplateType5> <BackgroundImageURI IsRelative="true" IsResource="false">ApplicationIcon_256x256.png</BackgroundImageURI> <Count>0</Count> <Title>NeodataTestApp</Title> </TemplateType5> </PrimaryToken> </Tokens> </App> </Deployment> Neodata Group srl Viale Vittorio Veneto 42 - Catania T / 9

4 4. API DELL SDK API DI ADAGIOADV AdAgioADV(PhoneApplicationPage Costruttore adpage) AdAgioADV(PhoneApplicationPage Costruttore adpage, string clientid, string positionid) AdAgioADV(PhoneApplicationPage Costruttore adpage, AdAgioADView adview) AdAgioADV(PhoneApplicationPage Costruttore adpage, AdAgioADView adview, string clientid, string positionid) 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 SetKw(String keywords) setta delle keyword separate da pipe ( ) void LoadAdv() void LoadInterstitial() void EnableLocation() void DisableLocation() (opzionale) effettua la richiesta di caricamento del banner effettua la richiesta di caricamento del banner interstitial abilita la localizzazione GPS disabilita la localizzazione GPS PROPRIETÀ DELL OGGETTO ADAGIOADV int RefreshRate string ClientId string PositionId setta l intervallo di tempo (in secondi) tra un refresh e il successivo. RefreshRate= 0 disabilita il refresh automatico del banner setta il clientid (comunicato da Neodata) setta l identificativo della posizione dell ad (comunicato da Neodata) Neodata Group srl Viale Vittorio Veneto 42 - Catania T / 9

5 EVENTHANDLER DELL OGGETTO ADAGIOADV EventHandler AdReceived Notifica la corretta ricezione dell ad EventHandler AdFailure Fallimento nella procedura di caricamento dell ad, dovuto ad un problema di rete, errore di configurazione o assenza di banner da mostrare. EventHandler AdClick Notifica dell avvenuto click sul banner 5. UTILIZZO IN FASE DI SVILUPPO 5.1. INSERIMENTO DELLE VIEW NEI LAYOUT Per poter integrare all interno di una PhoneApplicationPage una finestra AdAgioADView per la visualizzazione di banner pubblicitari è necessario inserire una view del tipo AdAgioSDK:AdAgioADView all interno del layout (tramite file XAML 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. ESEMPIO DI ISTANZA ADAGIOADVIEW TRAMITE XAML <AdAgioSDK:AdAgioADView x:name="adview1" VerticalAlignment="Bottom" Height="75" Width="480" Margin="0,0,0,75" /> 5.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(). I parametri obbligatori sono: - adpage: PhoneApplicationPage che richiede il banner - adview: risorsa rappresentante la view AdAgioADView o il relativo identificativo (istanziato nel file XAML di layout) - clientid: parametro comunicato da Neodata - positionid: parametro comunicato da Neodata Neodata Group srl Viale Vittorio Veneto 42 - Catania T / 9

6 ESEMPIO COMPLETO DI ISTANZIAZIONE BANNER TRAMITE LAYOUT XAML (1) XAML: <AdAgioSDK:AdAgioADView x:name="adview" Height="75" Width="480" /> C#: // Creazione di una istanza di AdAgioADV: AdAgioSDK.AdAgioADV advertising = new AdAgioSDK.AdAgioADV(this, adview); // Impostazione del ClientId, comunicato off band da Neodata: advertising.clientid = NEODATA_CLIENT_ID; // Impostazione del PositionID, comunicato off band da Neodata: advertising.positionid = NEODATA_POSITION_ID; // Impostazione delle keywords: advertising.setkw("these are example keywords"); // Disattivazione della geolocalizzazione per l istanza: advertising.disablelocation(); //Impostazione EventHandler advertising.adfailure += advertising_adfailure; advertising.adclick += advertising_adclick; advertising.adreceived += advertising_adreceived; try advertising.loadadv(); catch (Exception e) Debug.WriteLine(e.ToString()); /////////////////////////////////////////////////////// void advertising_adreceived(object sender, System.EventArgs e) Debug.WriteLine("@@@@@@@@ Evento AdReceived"); void advertising_adfailure(object sender, System.EventArgs e) Debug.WriteLine("@@@@@@@@ Evento AdFailure"); void advertising_adclick(object sender, System.EventArgs e) Debug.WriteLine("@@@@@@@@ Evento AdClick"); Neodata Group srl Viale Vittorio Veneto 42 - Catania T / 9

7 ESEMPIO COMPLETO DI ISTANZIAZIONE E RICHIESTA DI AD CON OGGETTO ADAGIOADVIEW CREATO PROGRAMMATICAMENTE //Creazione istanza AdAgioADView AdAgioSDK.AdAgioADView adview = new AdAgioSDK.AdAgioADView(); //Setting dimensioni 480x75 adview.width = 480; adview.height = 75; //Aggiunta oggetto AdAgioADView al layout LayoutRoot.Children.Add(adView); //Creazione istanza AdAgioADV attraverso i parametri inviati off band da Neodata (sintassi compatta) AdAgioSDK.AdAgioADV advertising = new AdAgioSDK.AdAgioADV(this, adview, NEODATA_CLIENT_ID, NEODATA_POSITION_ID); // Impostazione delle keywords: advertising.setkw("these are example keywords"); //Impostazione EventHandler advertising.adfailure += advertising_adfailure; advertising.adclick += advertising_adclick; advertising.adreceived += advertising_adreceived; try advertising.loadadv(); catch (Exception e) Debug.WriteLine(e.ToString()); Neodata Group srl Viale Vittorio Veneto 42 - Catania T / 9

8 5.3. BANNER ESPANDIBILI ED INTERSTITIAL La SDK è in grado di gestire banner di tipo espandibile ed interstitial, come da specifiche IAB MRAID ( Il banner espandibile è un particolare tipo di banner che viene visualizzato inizialmente a dimensioni ridotte, per poi espandersi al click dell utente. La gestione dell espansione del banner è totalmente a carico della SDK, ed equivale all apertura di una finestra modale sull app, opportunamente provvista di un bottone per la chiusura. Alla pressione sul tasto di chiusura il banner ritorna di dimensioni ridotte. Il banner di tipo interstitial, diversamente dal primo, si avvia direttamente espanso su una finestra modale fullscreen provvista di tasto Chiudi. Il click sul banner permetterà la visualizzazione della landing page su una nuova istanza del browser di sistema. Per consentire l erogazione del formato interstitial è necessario invocare il metodo LoadInterstitial() dell oggetto AdAgioADV REFRESH DEL BANNER E possibile impostare un valore di refresh per consentire l aggiornamento automatico del banner da visualizzare, attraverso la proprietà RefreshRate L intero RefreshRate indica il numero di secondi: impostando zero (0) l oggetto AdAgioADV non sarà mai aggiornato automaticamente COMPORTAMENTO DEL BANNER E possibile assegnare ad ogni banner un comportamento, ovvero mostrare/nascondere il banner per un certo numero di secondi e numero prefissato di volte. Il setting di tali parametri avviene su [ad.agio], in fase di caricamento del banner. Neodata Group srl Viale Vittorio Veneto 42 - Catania T / 9

9 5.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 (AdFailure). Il banner verrà visualizzato non appena sarà fatta una nuova chiamata in presenza di connettività (esplicitamente o all apertura di una nuova page con banner). 2. se al momento del refresh la rete manca ma precedentemente era stato possibile fare una request, continuerà ad essere visualizzato il banner precedentemente caricato, finchè non sarà possibile effettuare un nuovo refresh. Per ogni refresh in assenza di connettività verrà sempre notificato il fallimento (AdFailure). Neodata Group srl Viale Vittorio Veneto 42 - Catania T / 9