Introduzione ad Azure Mobile Engagement per app Xamarin.Android

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. Questa esercitazione illustra uno scenario di trasmissione semplice tramite 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).

Nota

Il servizio Azure Mobile Engagement verrà ritirato a marzo 2018 ed è attualmente disponibile solo per i clienti esistenti. Per altre informazioni, vedere Mobile Engagement.

Per completare questa esercitazione, è necessario disporre di:

Nota

Per completare l'esercitazione, è necessario disporre di un account Azure attivo. Se non si dispone di un account, è possibile creare un account di valutazione gratuita in pochi minuti. Per informazioni dettagliate, vedere la pagina relativa alla versione di valutazione gratuita di Azure.

Configurare Mobile Engagement per l'app Android

  1. Accedere al portale di Azure.
  2. Fare clic su Nuovo, quindi su Web e dispositivi mobili e infine su 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. Immettere le seguenti informazioni:

    • Nome: Nome of your raccolta di applicazioni
    • Piattaforme: selezionare le piattaforme di destinazione per l'app nel pannello Piattaforme che verrà aperto. Ad esempio, se è necessaria un'app sia per iOS che per Android, selezionare entrambe le piattaforme per creare due app in questa raccolta di app.

    • Sottoscrizione: selezionare la sottoscrizione di Azure.
    • Gruppo di risorse: selezionare il gruppo di risorse di Azure in cui inserire questa risorsa di Azure (Raccolta di app Mobile Engagement). È possibile scegliere di crearne uno nuovo.
    • Località: area in cui verranno archiviati i dati su questa raccolta di app e su questa app.
  4. Esplorare le raccolte di app Mobile Engagement facendo clic su Esplora e cercando 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.

  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.

  7. Fare clic sull'app creata per la piattaforma per cui si sta sviluppando.

  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.

Connettere l'app al back-end di Mobile Engagement

Questa esercitazione presenta una "integrazione di base", che è la configurazione minima necessaria per raccogliere i dati e inviare una notifica push.

Verrà creata un'app di base con Xamarin Studio per illustrare l'integrazione.

Creare un nuovo progetto Xamarin.Android

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

  2. Selezionare Android App (App Android), assicurarsi che il linguaggio selezionato sia C# e quindi fare clic su Next (Avanti).

  3. Specificare le informazioni richieste nei campi App Name (Nome app) e Organization Identifier (Identificatore organizzazione). Assicurarsi di selezionare Google Play Services con un segno di spunta e quindi fare clic su Next (Avanti).

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

Xamarin Studio creerà l'app in cui verrà integrato Mobile Engagement.

Connettere l'app al back-end di Mobile Engagement

  1. Fare clic con il pulsante destro del mouse sulla cartella Packages (Pacchetti) nelle finestre della soluzione, quindi scegliere Add Packages... (Aggiungi pacchetti)

  2. Cercare Microsoft Azure Mobile Engagement Xamarin SDK e aggiungerlo alla soluzione.

  3. Aprire MainActivity.cs e aggiungere le istruzioni using seguenti:

     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. Assicurarsi di aggiungere ConnectionString.

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

Aggiungere le autorizzazioni e una dichiarazione del servizio

  1. Aprire il file Manifest.xml nella cartella Properties. Selezionare la scheda Source per aggiornare direttamente l'origine XML.
  2. Aggiungere queste autorizzazioni al file Manifest.xml, nella cartella Properties del progetto, immediatamente prima o dopo il tag <application>:

     <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:

     <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. Questo è il valore visualizzato nel menu Impostazioni , che mostra all'utente i servizi in esecuzione nel dispositivo. È possibile aggiungere la parola "Service" all'etichetta, ad esempio.

Inviare una schermata a 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. Per eseguire questa operazione, assicurarsi che MainActivity erediti da EngagementActivity anziché da 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.

    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 reale

Questa sezione descrive come connettere l'app al back-end di Mobile Engagement usando la funzionalità di monitoraggio in tempo reale di Mobile Engagement.

  1. Nell'account Azure Mobile Engagement, accertarsi di selezionare l'app che si desidera monitorare e gestire nel portale di Mobile Engagement. Accedere al portale di Mobile Engagement facendo clic sul pulsante Engagement nella parte inferiore.

  2. Viene visualizzato il portale Mobile Engagement. Se non è selezionata la scheda Monitoraggio, fare clic su Monitoraggio.
  3. Verranno visualizzati, in tempo reale, tutti i dispositivi in cui l'app verrà avviata.
  4. Avviare l'app. 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.

Abilitare le notifiche push e la messaggistica in-app

Mobile Engagement consente di interagire con gli utenti e COINVOLGERLI tramite notifiche push e messaggistica in-app nel contesto di campagne. Questo modulo è denominato REACH nel portale di Mobile Engagement. Le sezioni seguenti consentono di configurare l'app per la ricezione.

Creare un progetto Google Firebase con chiave API

Nota

Per completare questa procedura, è necessario disporre di un account Google con un indirizzo di posta elettronica verificato. Per creare un nuovo account Google, visitare il sito Web all'indirizzo accounts.google.com.

  1. Passare alla console di Firebase ed eseguire l'accesso con le credenziali dell'account Google.
  2. Fare clic sul pulsante Create new Project (Crea nuovo progetto) per creare un nuovo progetto. In alternativa, è possibile fare clic su Import Google Project (Importa progetto di Google) per importare un progetto esistente.
  3. Se si è scelto di creare un nuovo progetto, specificare un nome progetto e scegliere un paese/area geografica.
  4. Nella pagina del progetto fare clic sull'ingranaggio delle impostazioni nell'angolo superiore sinistro. Nel menu fare clic su Project settings (Impostazioni del progetto).
  5. Fare clic sulla scheda Cloud Messaging in alto.
  6. Prendere nota dei valori di Server Key (Chiave server) e Sender ID (ID mittente), che verranno usati più avanti nel file manifesto Android.

Aggiornare il file manifesto per abilitare le notifiche

Copiare le risorse di messaggistica in-app seguenti nel file Manifest.xml tra i tag <application> e </application>.

    <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 notifiche

Incollare il frammento di codice XML seguente nel file Manifest.xml tra i tag <application> e </application>.

    <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. Essa è facoltativa per le notifiche in-app, ma obbligatoria per le notifiche di sistema. Android rifiuterà le notifiche di sistema con icone non valide.

Assicurarsi di usare un'icona esistente in una delle cartelle drawable (ad esempio engagement_close.png). mipmap non è supportata.

Nota

È consigliabile non usare l'icona di avvio. poiché ha una risoluzione diversa e si trova in genere nelle cartelle mipmap, che non sono supportate.

Per le app reali, è possibile usare un'icona adatta alle notifiche in base alle linee guida per la progettazione per Android.

Suggerimento

Per assicurarsi di usare la risoluzione corretta per l'icona, vedere questi esempi. 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. È possibile scegliere le cartelle drawable da usare con una risoluzione specifica per ogni versione dell'icona.

Abilitare l'app per la ricezione delle notifiche push GCM

  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. L'uso di \n è intenzionale. Assicurarsi di inserirlo alla fine del numero di progetto.

     <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>. Sostituire il nome del pacchetto .

     <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> . Sostituire <Your package name> con il nome effettivo del pacchetto dell'applicazione.

     <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 GCM

Per consentire a Mobile Engagement di inviare notifiche push per conto dell'utente, è necessario concedere l'accesso alla chiave API. A tale scopo, è necessario configurare la chiave e immetterla nel portale di Mobile Engagement.

  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.

  2. Fare quindi clic sulla sezione Impostazioni -> Push nativo per immettere la chiave GCM:

  3. Fare clic sull'icona Modifica vicino a Chiave API nella sezione delle impostazioni GCM, come illustrato di seguito:

  4. Nella finestra a comparsa incollare la chiave del server GCM ottenuta prima e quindi fare clic su OK.

Inviare una notifica all'app

A questo punto si crea una campagna di notifica push semplice che invia una notifica push all'app.

  1. Passare alla scheda REACH nel portale di Mobile Engagement.
  2. Fare clic su Nuovo annuncio per creare una campagna di notifica push.

  3. Impostare il primo campo della campagna seguendo questa procedura:

    a. Assegnare un nome alla campagna.

    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.

    c. Per Ora di recapito selezionare In qualsiasi momento per consentire all'app di ricevere una notifica anche se non è stata avviata.

    d. Nel testo della notifica digitare il titolo che apparirà in grassetto nel push.

    e. Digitare quindi il messaggio

  4. Scorrere verso il basso e nella sezione Contenuto selezionare Notification only (Solo notifica).

  5. L'impostazione della campagna più semplice possibile è stata completata. Ora scorrere nuovamente verso il basso e fare clic sul pulsante Crea per salvare la campagna.
  6. Come ultimo passaggio, fare clic su Attiva per attivare la campagna e inviare le notifiche push.