Introduzione ad Azure Mobile Engagement per app Xamarin.AndroidGet Started with Azure Mobile Engagement for Xamarin.Android Apps

Questo argomento descrive come usare Azure Mobile Engagement per ottenere informazioni sull'uso dell'app e sull'invio di notifiche push a utenti segmentati di un'applicazione Xamarin.Android.This topic shows you how to use Azure Mobile Engagement to understand your app usage and how to send push notifications to segmented users of a Xamarin.Android application. Questa esercitazione illustra uno scenario di trasmissione semplice tramite Mobile Engagement.This tutorial demonstrates the simple broadcast scenario using Mobile Engagement. Verrà creata un'app Xamarin.Android vuota che raccoglie dati di base e riceve notifiche push tramite il servizio Google Cloud Messaging (GCM).In it, you create a blank Xamarin.Android app that collects basic data and receives push notifications using Google Cloud Messaging (GCM).

Nota

Il servizio Azure Mobile Engagement verrà ritirato a marzo 2018 ed è attualmente disponibile solo per i clienti esistenti.The Azure Mobile Engagement service will be retired March 2018 and is currently only available to existing customers. Per altre informazioni, vedere Mobile Engagement.For more information, see Mobile Engagement.

Per completare questa esercitazione, è necessario disporre di:This tutorial requires the following:

Nota

Per completare l'esercitazione, è necessario disporre di un account Azure attivo.To complete this tutorial, you must have an active Azure account. Se non si dispone di un account, è possibile creare un account di valutazione gratuita in pochi minuti.If you don't have an account, you can create a free trial account in just a couple of minutes. Per informazioni dettagliate, vedere la pagina relativa alla versione di valutazione gratuita di Azure.For details, see Azure Free Trial.

Configurare Mobile Engagement per l'app AndroidSetup Mobile Engagement for your Android app

  1. Accedere al portale di Azure.Log on to the Azure Portal.
  2. Fare clic su Nuovo, quindi su Web e dispositivi mobili e infine su Mobile Engagement.Click on New, then Web + Mobile, and then Mobile Engagement.

  3. Nel pannello New Mobile Engagement App Collection (Nuova raccolta di app Mobile Engagement) visualizzato si creerà una raccolta di app invece che un'app come nel portale di Azure classico.In the New Mobile Engagement App Collection blade that appears, you will be creating an App Collection instead of an App like in the Azure classic portal. Immettere le seguenti informazioni:Enter the following information:

    • Nome: Nome of your raccolta di applicazioniName: Name of your application collection
    • Piattaforme: selezionare le piattaforme di destinazione per l'app nel pannello Piattaforme che verrà aperto.Platforms: Select target platforms for your app on the Platforms blade which will open up. Ad esempio,E.g. se è necessaria un'app sia per iOS che per Android, selezionare entrambe le piattaforme per creare due app in questa raccolta di app.if you want an app for both iOS & Android then select both platforms and you will get two apps created under this app collection.

    • Sottoscrizione: selezionare la sottoscrizione di Azure.Subscription: Select the Azure subscription.
    • Gruppo di risorse: selezionare il gruppo di risorse di Azure in cui inserire questa risorsa di Azure (Raccolta di app Mobile Engagement).Resource group: Select the Azure Resource group in which you want this Azure resource (Mobile Engagement App Collection). È possibile scegliere di crearne uno nuovo.You can choose to create a new one.
    • Località: area in cui verranno archiviati i dati su questa raccolta di app e su questa app.Location: Region where the data about this app collection & app will be stored.
  4. Esplorare le raccolte di app Mobile Engagement facendo clic su Esplora e cercando Mobile EngagementBrowse through the Mobile Engagement app collections by clicking Browse and search for Mobile Engagement

  5. Verrà visualizzato un elenco di raccolte di app Mobile Engagement: assicurarsi di avere la stessa sottoscrizione di Azure in cui è stata creata la raccolta di app.You will be shown a list of Mobile Engagement App Collections - make sure you have the same Azure subscription where you created your App Collection.

  6. Fare clic sulla raccolta di app creata nel passaggio precedente per aprire il pannello della risorsa raccolta di app che visualizzerà le diverse app presenti in questa raccolta di app.Click on the App Collection that you created in the prior step to open up the App Collection resource blade which will show the different apps present inside this app collection.

  7. Fare clic sull'app creata per la piattaforma per cui si sta sviluppando.Click on the App created for the platform you are developing for.

  8. Fare clic sul pulsante di comando Informazioni di connessione in alto per aprire il pannello Informazioni di connessione e copiare la stringa di connessione.Click on Connection Info command button at the top to open up the Connection Info blade and copy the connection string from there.

Connettere l'app al back-end di Mobile EngagementConnect your app to the Mobile Engagement backend

Questa esercitazione presenta una "integrazione di base", che è la configurazione minima necessaria per raccogliere i dati e inviare una notifica push.This tutorial presents a "basic integration", which is the minimal set required to collect data and send a push notification.

Verrà creata un'app di base con Xamarin Studio per illustrare l'integrazione.We will create a basic app with Xamarin Studio to demonstrate the integration.

Creare un nuovo progetto Xamarin.AndroidCreate a new Xamarin.Android project

  1. Avviare Xamarin Studio e passare a File -> New -> (Nuovo) Solution (Soluzione)Launch Xamarin Studio Go to File -> New -> Solution

  2. Selezionare Android App (App Android), assicurarsi che il linguaggio selezionato sia C# e quindi fare clic su Next (Avanti).Select Android App then make sure the selected language is C# and click Next.

  3. Specificare le informazioni richieste nei campi App Name (Nome app) e Organization Identifier (Identificatore organizzazione).Fill in the App Name and the Organization Identifier. Assicurarsi di selezionare Google Play Services con un segno di spunta e quindi fare clic su Next (Avanti).Make sure to checkmark Google Play Services and then click Next.

  4. Aggiornare i campi Project Name (Nome progetto), Solution Name (Nome soluzione) e Location (Posizione), se necessario, e fare clic su Create (Crea).Update the Project Name, Solution Name and Location if required and click Create.

Xamarin Studio creerà l'app in cui verrà integrato Mobile Engagement.Xamarin Studio will create the app in which we will integrate Mobile Engagement.

Connettere l'app al back-end di Mobile EngagementConnect your app to Mobile Engagement backend

  1. Fare clic con il pulsante destro del mouse sulla cartella Packages (Pacchetti) nelle finestre della soluzione, quindi scegliere Add Packages... (Aggiungi pacchetti)Right click the Packages folder in the Solution windows and select Add Packages...

  2. Cercare Microsoft Azure Mobile Engagement Xamarin SDK e aggiungerlo alla soluzione.Search for the Microsoft Azure Mobile Engagement Xamarin SDK and add it to your solution.

  3. Aprire MainActivity.cs e aggiungere le istruzioni using seguenti:Open MainActivity.cs and add the following using statements:

     using Microsoft.Azure.Engagement;
     using Microsoft.Azure.Engagement.Activity;
    
  4. Nel metodo OnCreate aggiungere quanto segue per inizializzare la connessione con il back-end di Mobile Engagement.In the OnCreate method, add the following to initialize the connection with Mobile Engagement backend. Assicurarsi di aggiungere ConnectionString.Make sure to add your ConnectionString.

     EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
     engagementConfiguration.ConnectionString = "YourConnectionStringFromAzurePortal";
     EngagementAgent.Init(engagementConfiguration);
    

Aggiungere le autorizzazioni e una dichiarazione del servizioAdd permissions and a service declaration

  1. Aprire il file Manifest.xml nella cartella Properties.Open up the Manifest.xml file under the Properties folder. Selezionare la scheda Source per aggiornare direttamente l'origine XML.Select Source tab so that you directly update the XML source.
  2. Aggiungere queste autorizzazioni al file Manifest.xml, nella cartella Properties del progetto, immediatamente prima o dopo il tag <application>:Add these permissions to the Manifest.xml (which can be found under the Properties folder) of your project immediately before or after the <application> tag:

     <uses-permission android:name="android.permission.INTERNET"/>
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
     <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
     <uses-permission android:name="android.permission.VIBRATE" />
     <uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION"/>
    
  3. Aggiungere quanto indicato sotto tra i tag <application> e </application> per dichiarare il servizio agente:Add the following between the <application> and </application> tags to declare the agent service:

     <service
          android:name="com.microsoft.azure.engagement.service.EngagementService"
          android:exported="false"
          android:label="<Your application name>"
          android:process=":Engagement"/>
    
  4. Nel codice appena incollato sostituire "<Your application name>" nell'etichetta.In the code you just pasted, replace "<Your application name>" in the label. Questo è il valore visualizzato nel menu Impostazioni , che mostra all'utente i servizi in esecuzione nel dispositivo.This is displayed in the Settings menu where users can see services running on the device. È possibile aggiungere la parola "Service" all'etichetta, ad esempio.You can add the word "Service" in that label for example.

Inviare una schermata a Mobile EngagementSend a screen to Mobile Engagement

Per iniziare a inviare dati e assicurarsi che gli utenti siano attivi, è necessario inviare almeno una schermata al back-end di Mobile Engagement.In order to start sending data and ensuring the users are active, you must send at least one screen to the Mobile Engagement backend. Per eseguire questa operazione, assicurarsi che MainActivity erediti da EngagementActivity anziché da Activity.For doing this - ensure that the MainActivity inherits from EngagementActivity instead of Activity.

public class MainActivity : EngagementActivity

In alternativa, se non è possibile ereditare da EngagementActivity è necessario aggiungere i metodi .StartActivity e .EndActivity rispettivamente in OnResume e OnPause.Alternatively, if you cannot inherit from EngagementActivity then you must add .StartActivity and .EndActivity methods in OnResume and OnPause respectively.

    protected override void OnResume()
        {
            EngagementAgent.StartActivity(EngagementAgentUtils.BuildEngagementActivityName(Java.Lang.Class.FromType(this.GetType())), null);
            base.OnResume();             
        }

        protected override void OnPause()
        {
            EngagementAgent.EndActivity();
            base.OnPause();            
        }

Connettere l'app con monitoraggio in tempo realeConnect app with real-time monitoring

Questa sezione descrive come connettere l'app al back-end di Mobile Engagement usando la funzionalità di monitoraggio in tempo reale di Mobile Engagement.This section shows you how to connect your app to the Mobile Engagement backend by using the Mobile Engagement's real-time monitoring feature.

  1. Nell'account Azure Mobile Engagement, accertarsi di selezionare l'app che si desidera monitorare e gestire nel portale di Mobile Engagement.In your Azure Mobile Engagement account, make sure you select the app you wish to monitor and manage in the Mobile Engagement portal. Accedere al portale di Mobile Engagement facendo clic sul pulsante Engagement nella parte inferiore.Navigate to your Mobile Engagement portal by clicking the Engage button at the bottom.

  2. Viene visualizzato il portale Mobile Engagement.You will land in the Mobile Engagement portal. Se non è selezionata la scheda Monitoraggio, fare clic su Monitoraggio.If the Monitor tab is not selected, click on the Monitor.
  3. Verranno visualizzati, in tempo reale, tutti i dispositivi in cui l'app verrà avviata.The monitor is ready to show you any device in real time, which will start your app.
  4. Avviare l'app.Start your app now. Se l'integrazione è corretta si noterà una sessione di monitoraggio, che significa che l'app ora è collegata al back-end di Mobile Engagement e sta inviando dati ad esso.You should see one session in the monitor if your integration is correct which means that your app is now connected to the Mobile Engagement backend and is sending data to it.

Abilitare le notifiche push e la messaggistica in-appEnable push notifications and in-app messaging

Mobile Engagement consente di interagire con gli utenti e COINVOLGERLI tramite notifiche push e messaggistica in-app nel contesto di campagne.Mobile Engagement allows you to interact with and REACH your users with push notifications and in-app messaging in the context of campaigns. Questo modulo è denominato REACH nel portale di Mobile Engagement.This module is called REACH in the Mobile Engagement portal. Le sezioni seguenti consentono di configurare l'app per la ricezione.The following sections sets up your app to receive them.

Creare un progetto Google Firebase con chiave APICreate a Google Firebase project with API key

Nota

Per completare questa procedura, è necessario disporre di un account Google con un indirizzo di posta elettronica verificato.To complete this procedure, you must have a Google account that has a verified email address. Per creare un nuovo account Google, visitare il sito Web all'indirizzo accounts.google.com.To create a new Google account, go to accounts.google.com.

  1. Passare alla console di Firebase ed eseguire l'accesso con le credenziali dell'account Google.Navigate to the Firebase Console and sign-in with your Google account credentials.
  2. Fare clic sul pulsante Create new Project (Crea nuovo progetto) per creare un nuovo progetto.Click on Create new Project button to create a new project. In alternativa, è possibile fare clic su Import Google Project (Importa progetto di Google) per importare un progetto esistente.Alternatively, you can also click on Import Google Project to import and existing project.
  3. Se si è scelto di creare un nuovo progetto, specificare un nome progetto e scegliere un paese/area geografica.If you opted for creating a new project then provide a Project name and choose a Country/Region.
  4. Nella pagina del progetto fare clic sull'ingranaggio delle impostazioni nell'angolo superiore sinistro.On your project page, click the Settings cog wheel at the top left. Nel menu fare clic su Project settings (Impostazioni del progetto).In the menu, click on Project settings.
  5. Fare clic sulla scheda Cloud Messaging in alto.Click on the Cloud Messaging tab at the top.
  6. Prendere nota dei valori di Server Key (Chiave server) e Sender ID (ID mittente), che verranno usati più avanti nel file manifesto Android.Make a note of the Server Key and the Sender ID that you will use later in the Android Manifest file.

Aggiornare il file manifesto per abilitare le notificheUpdate manifest file to enable notifications

Copiare le risorse di messaggistica in-app seguenti nel file Manifest.xml tra i tag <application> e </application>.Copy the in-app messaging resources below into your Manifest.xml between the <application> and </application> tags.

    <activity android:name="com.microsoft.azure.engagement.reach.activity.EngagementTextAnnouncementActivity" android:theme="@android:style/Theme.Light" android:exported="false">
          <intent-filter>
            <action android:name="com.microsoft.azure.engagement.reach.intent.action.ANNOUNCEMENT"/>
            <category android:name="android.intent.category.DEFAULT" />
            <data android:mimeType="text/plain" />
          </intent-filter>
    </activity>
    <activity android:name="com.microsoft.azure.engagement.reach.activity.EngagementWebAnnouncementActivity" android:theme="@android:style/Theme.Light" android:exported="false">
        <intent-filter>
            <action android:name="com.microsoft.azure.engagement.reach.intent.action.ANNOUNCEMENT"/>
            <category android:name="android.intent.category.DEFAULT" />
            <data android:mimeType="text/html" />
        </intent-filter>
    </activity>
    <activity android:name="com.microsoft.azure.engagement.reach.activity.EngagementPollActivity" android:theme="@android:style/Theme.Light" android:exported="false">
        <intent-filter>
            <action android:name="com.microsoft.azure.engagement.reach.intent.action.POLL"/>
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </activity>
    <activity android:name="com.microsoft.azure.engagement.reach.activity.EngagementLoadingActivity" android:theme="@android:style/Theme.Dialog" android:exported="false">
        <intent-filter>
            <action android:name="com.microsoft.azure.engagement.reach.intent.action.LOADING"/>
            <category android:name="android.intent.category.DEFAULT"/>
        </intent-filter>
    </activity>
    <receiver android:name="com.microsoft.azure.engagement.reach.EngagementReachReceiver" android:exported="false">
        <intent-filter>
            <action android:name="android.intent.action.BOOT_COMPLETED"/>
            <action android:name="com.microsoft.azure.engagement.intent.action.AGENT_CREATED"/>
            <action android:name="com.microsoft.azure.engagement.intent.action.MESSAGE"/>
            <action android:name="com.microsoft.azure.engagement.reach.intent.action.ACTION_NOTIFICATION"/>
            <action android:name="com.microsoft.azure.engagement.reach.intent.action.EXIT_NOTIFICATION"/>
            <action android:name="com.microsoft.azure.engagement.reach.intent.action.DOWNLOAD_TIMEOUT"/>
        </intent-filter>
    </receiver>
    <receiver android:name="com.microsoft.azure.engagement.reach.EngagementReachDownloadReceiver">
        <intent-filter>
            <action android:name="android.intent.action.DOWNLOAD_COMPLETE"/>
        </intent-filter>
    </receiver>

Specificare un'icona per le notificheSpecify an icon for notifications

Incollare il frammento di codice XML seguente nel file Manifest.xml tra i tag <application> e </application>.Paste the following XML snippet in your Manifest.xml between the <application> and </application> tags.

    <meta-data android:name="engagement:reach:notification:icon" android:value="engagement_close"/>

In questo modo si definisce l'icona che viene visualizzata sia nelle notifiche di sistema sia nelle notifiche in-app.This defines the icon that is displayed both in system and in-app notifications. Essa è facoltativa per le notifiche in-app, ma obbligatoria per le notifiche di sistema.It is optional for in-app notifications however mandatory for system notifications. Android rifiuterà le notifiche di sistema con icone non valide.Android will rejects system notifications with invalid icons.

Assicurarsi di usare un'icona esistente in una delle cartelle drawable (ad esempio engagement_close.png).Make sure you are using an icon that exists in one of the drawable folders (like engagement_close.png). mipmap non è supportata.mipmap folder isn't supported.

Nota

È consigliabile non usare l'icona di avvio.You should not use the launcher icon. poiché ha una risoluzione diversa e si trova in genere nelle cartelle mipmap, che non sono supportate.It has a different resolution and is usually in the mipmap folders, which we don't support.

Per le app reali, è possibile usare un'icona adatta alle notifiche in base alle linee guida per la progettazione per Android.For real apps, you can use an icon that is suitable for notifications per Android design guidelines.

Suggerimento

Per assicurarsi di usare la risoluzione corretta per l'icona, vedere questi esempi.To be sure to use correct icon resolutions, you can look at these examples. Scorrere verso il basso fino alla sezione Notification, fare clic su un'icona e quindi su PNGS per scaricare il set di icone di tipo drawable.Scroll down to the Notification section, click an icon, and then click PNGS to download the icon drawable set. È possibile scegliere le cartelle drawable da usare con una risoluzione specifica per ogni versione dell'icona.You can see what drawable folders with which resolution to use for each version of the icon.

Abilitare l'app per la ricezione delle notifiche push GCMEnable your app to receive GCM push notifications

  1. Incollare quanto segue nel file Manifest.xml tra i tag <application> e </application> dopo aver sostituito il Sender ID ottenuto dalla console del progetto Firebase.Paste the following into your Manifest.xml between the <application> and </application> tags after replacing the Sender ID obtained from your Firebase project console. L'uso di \n è intenzionale. Assicurarsi di inserirlo alla fine del numero di progetto.The \n is intentional so make sure that you end the project number with it.

     <meta-data android:name="engagement:gcm:sender" android:value="************\n" />
    
  2. Incollare il codice seguente nel file Manifest.xml tra i tag <application> e </application>.Paste the code below into your Manifest.xml between the <application> and </application> tags. Sostituire il nome del pacchetto .Replace the package name .

     <receiver android:name="com.microsoft.azure.engagement.gcm.EngagementGCMEnabler"
     android:exported="false">
         <intent-filter>
             <action android:name="com.microsoft.azure.engagement.intent.action.APPID_GOT" />
         </intent-filter>
     </receiver>
    
     <receiver android:name="com.microsoft.azure.engagement.gcm.EngagementGCMReceiver" android:permission="com.google.android.c2dm.permission.SEND">
         <intent-filter>
             <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
             <action android:name="com.google.android.c2dm.intent.RECEIVE" />
             <category android:name="<Your package name>" />
         </intent-filter>
     </receiver>
    
  3. Aggiungere l'ultimo set di autorizzazioni evidenziate prima del tag <application> .Add the last set of permissions that are highlighted before the <application> tag. Sostituire <Your package name> con il nome effettivo del pacchetto dell'applicazione.Replace <Your package name> by the actual package name of your application.

     <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
     <uses-permission android:name="<Your package name>.permission.C2D_MESSAGE" />
     <permission android:name="<Your package name>.permission.C2D_MESSAGE" android:protectionLevel="signature" />
    

Concedere a Mobile Engagement l'accesso alla chiave API GCMGrant Mobile Engagement access to your GCM API Key

Per consentire a Mobile Engagement di inviare notifiche push per conto dell'utente, è necessario concedere l'accesso alla chiave API.To allow Mobile Engagement to send push notifications on your behalf, you need to grant it access to your API Key. A tale scopo, è necessario configurare la chiave e immetterla nel portale di Mobile Engagement.This is done by configuring and entering your key into the Mobile Engagement portal.

  1. Nel portale di Azure classico verificare che l'app usata per questo progetto sia aperta e fare clic sul pulsante Attiva nella parte inferiore della schermata.From your Azure Classic Portal, ensure you're in the app we're using for this project, and then click the Engage button at the bottom:

  2. Fare quindi clic sulla sezione Impostazioni -> Push nativo per immettere la chiave GCM:Then click the Settings -> Native Push section to enter your GCM Key:

  3. Fare clic sull'icona Modifica vicino a Chiave API nella sezione delle impostazioni GCM, come illustrato di seguito:Click the Edit icon in front of API Key in the GCM Settings section as shown below:

  4. Nella finestra a comparsa incollare la chiave del server GCM ottenuta prima e quindi fare clic su OK.In the pop-up, paste the GCM Server Key you obtained before and then click Ok.

Inviare una notifica all'appSend a notification to your app

A questo punto si crea una campagna di notifica push semplice che invia una notifica push all'app.We will now create a simple push notification campaign that sends a push notification to our app.

  1. Passare alla scheda REACH nel portale di Mobile Engagement.Navigate to the REACH tab in your Mobile Engagement portal.
  2. Fare clic su Nuovo annuncio per creare una campagna di notifica push.Click New announcement to create your push notification campaign.

  3. Impostare il primo campo della campagna seguendo questa procedura:Set up the first field of your campaign through the following steps:

    a.a. Assegnare un nome alla campagna.Name your campaign.

    b.b. Selezionare Notifica di sistema -> Semplice per Tipo di recapito: si tratta di un tipo di notifica push Android semplice con un titolo e una breve riga di testo.Select the Delivery type as System notification -> Simple: This is the simple Android push notification type that features a title and a small line of text.

    c.c. Per Ora di recapito selezionare In qualsiasi momento per consentire all'app di ricevere una notifica anche se non è stata avviata.Select Delivery time as Any time to allow the app to receive a notification whether the app is started or not.

    d.d. Nel testo della notifica digitare il titolo che apparirà in grassetto nel push.In the notification text type the Title which will be in bold in the push.

    e.e. Digitare quindi il messaggioThen type your Message

  4. Scorrere verso il basso e nella sezione Contenuto selezionare Notification only (Solo notifica).Scroll down, and in the Content section, select Notification only.

  5. L'impostazione della campagna più semplice possibile è stata completata.You're done setting the most basic campaign possible. Ora scorrere nuovamente verso il basso e fare clic sul pulsante Crea per salvare la campagna.Now scroll down again and click the Create button to save your campaign.
  6. Come ultimo passaggio, fare clic su Attiva per attivare la campagna e inviare le notifiche push.Last step: click Activate to activate your campaign to send push notifications.