Introduzione a Azure Mobile Engagement per app 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 per Android. Questa esercitazione illustra uno scenario di trasmissione semplice tramite Mobile Engagement. Si creerà un'app per Android vuota che raccoglie dati di base e riceve notifiche push tramite il servizio Google Cloud Messaging (GCM).

Prerequisiti

Per completare questa esercitazione, è necessario disporre di Android Developer Toolsche include l'ambiente di sviluppo integrato di Android Studio e la piattaforma Android più recente.

È necessario anche Mobile Engagement Android SDK.

Importante

Per completare l'esercitazione, è necessario 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. Si crea un'app di base con Android Studio per illustrare l'integrazione.

La documentazione relativa all'integrazione completa è disponibile in Integrazione di Android SDK per Azure Mobile Engagement.

Creare un progetto Android

  1. Avviare Android Studio e nella finestra popup selezionare Start a new Android Studio project (Avvia un nuovo progetto di Android Studio).

  2. Specificare il nome dell'app e il dominio aziendale. Prendere nota delle informazioni specificate perché saranno necessarie successivamente. Fare clic su Next.

  3. Selezionare il fattore di forma di destinazione e il livello di API e quindi fare clic su Next.

    Nota

    Mobile Engagement richiede almeno un livello API 10 (Android 2.3.3).

  4. Selezionare Blank Activity (Attività vuota), che sarà l'unica schermata disponibile per l'app, e fare clic su Next (Avanti).

  5. Lasciare quindi invariati i valori predefiniti e fare clic su Finish.

Android Studio crea l'app dimostrativa in cui viene integrato Mobile Engagement.

Includere nel progetto la libreria SDK

  1. Scaricare Mobile Engagement SDK per Android.
  2. Estrarre il file di archivio in una cartella nel computer.
  3. Identificare la libreria con estensione jar per la versione corrente di questo SDK e copiarla negli Appunti.

  4. Passare alla sezione Project (1) e incollare il file con estensione jar nella cartella delle librerie (2).

  5. Per caricare la libreria, sincronizzare il progetto.

Connettere l'app al back-end di Mobile Engagement usando la stringa di connessione

  1. Copiare le righe di codice seguenti nella creazione dell'attività. L'operazione deve essere eseguita in una sola posizione dell'applicazione, in genere nell'attività principale. Per questa app di esempio, aprire MainActivity nella cartella src -> main -> java e aggiungere quanto segue:

     EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
     engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
     EngagementAgent.getInstance(this).init(engagementConfiguration);
    
  2. Risolvere i riferimenti premendo ALT+INVIO o aggiungendo le istruzioni import seguenti:

     import com.microsoft.azure.engagement.EngagementAgent;
     import com.microsoft.azure.engagement.EngagementConfiguration;
    
  3. Tornare al portale di Azure classico, nella pagina Informazioni di connessione dell'app, e copiare la Stringa di connessione.

  4. Incollarla nel parametro setConnectionString, sostituendo l'intera stringa visualizzata nel codice seguente:

     engagementConfiguration.setConnectionString("Endpoint=my-company-name.device.mobileengagement.windows.net;SdkKey=********************;AppId=*********");
    

Aggiungere le autorizzazioni e una dichiarazione del servizio

  1. Aggiungere queste autorizzazioni al file Manifest.xml 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"/>
    
  2. Per dichiarare il servizio agente, aggiungere questo codice tra i tag <application> e </application>:

     <service
          android:name="com.microsoft.azure.engagement.service.EngagementService"
          android:exported="false"
          android:label="<Your application name>"
          android:process=":Engagement"/>
    
  3. Nel codice incollato sostituire "<Your application name>" nell'etichetta, che viene visualizzata nel menu Impostazioni in cui è possibile visualizzare 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 (Activity) al back-end di Mobile Engagement.

Accedere a MainActivity.java e aggiungere quanto segue per sostituire la classe di base di MainActivity con EngagementActivity:

public class MainActivity extends EngagementActivity {
Nota

Se la classe base non è Activity, vedere Reporting avanzato in Android per informazioni su come ereditare da classi diverse.

Impostare come commento la riga seguente per questo semplice scenario di esempio:

// setSupportActionBar(toolbar);

Per mantenere ActionBar nell'app, vedere Opzioni di segnalazione con Engagement in Android.

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

Durante una campagna, Mobile Engagement consente di interagire con gli utenti e coinvolgerli tramite notifiche push e messaggistica in-app. Questo modulo è denominato REACH nel portale di Mobile Engagement. La sezione seguente consente di configurare l'app per la ricezione.

Copiare le risorse dell'SDK nel progetto

  1. Tornare al contenuto scaricato dell'SDK e copiare la cartella res .

  2. Tornare ad Android Studio, selezionare la directory main dei file del progetto e incollarla per aggiungere le risorse al progetto.

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.

Passaggi successivi

Per ottenere informazioni dettagliate sull'integrazione dell'SDK, vedere Android SDK .