Prise en main d'Android Studio et des notifications push - XBOX Game Development Documentation

Vue d’ensemble

Ce tutoriel a été conçu pour vous aider à mettre rapidement en place l’intégration Android de PlayFab avec les notifications push. Les notifications push nécessitent une configuration dans plusieurs systèmes. Avant de commencer, voyons comment fonctionne l’infrastructure. Quatre entités participent au processus :

Google Play Services
Firebase Cloud Messaging Services (FCM, built on top of the old Google Cloud Messaging.)
PlayFab Services
Client Applications

1. Google Play Services

Google Play Services identifie votre page sur le Play Store à l’aide d’un nom de package. Par exemple : com.bob.games.matchthree. Une fois inscrit dans Google Play, le nom de package devient un ID d’application unique et sert à de nombreuses fins, de l’installation au moyen du Play Store à la prévention de l’usurpation d’identité.

2. Firebase Cloud Messaging (FCM)

Les services Firebase Cloud Messaging vous offrent un système infonuagique permettant d’envoyer, d’acheminer et de distribuer vos notifications push. Ils permettent également à d’autres services (comme PlayFab) d’envoyer des notifications push en votre nom à l’aide de la clé de serveur FCM.

3. Services PlayFab

Les services PlayFab utilisent ensuite la clé de serveur FCM pour envoyer des notifications push à vos clients.

4. Services clients

Enfin, votre application cliente peut recevoir les notifications et les traiter selon ses besoins.

Répartition en quatre parties

Par conséquent, nous devons configurer 4 systèmes différents. Pour ce faire, notre tutoriel est divisé en 4 chapitres, chacun couvrant la configuration d’un élément.

L’ordre dans lequel vous configurez les systèmes est important.

Prérequis

Vous devez disposer d’un compte Google.
Vous devez disposer d’un compte PlayFab.
Une icône de notification générée à l’aide du générateur d’icônes de notification d’Android Asset Studio.

Scénario

Dans cette section du tutoriel, nous allons assembler une application appelée Foo PlayFab App. Il s’agit d’une application Android qui offre les fonctions suivantes :

Elle se connecte à PlayFab à l’aide d’un ID d’appareil Android.
Elle reçoit des notifications push de PlayFab.

Notre nom de package sera com.foo.playfab.app.

Veillez à utiliser votre propre nom de package et votre propre titre lorsque vous suivez ce tutoriel.

Chapitre 1 : configuration de Firebase

Commencez la configuration de Firebase à l’aide de sa page de console officielle. Une page s’affiche, sur laquelle vous pouvez ajouter un nouveau projet.

Pour ce faire, sélectionnez la zone Add project, comme illustré dans l’image suivante.

Vous êtes invité à fournir un Project Name (dans ce tutoriel, nous utilisons Foo PlayFab App, mais veillez à choisir votre propre nom lorsque vous suivez ce tutoriel).
Sélectionnez le bouton Create Project pour passer à l’étape suivante.

Vous êtes redirigé vers le New Project Dashboard.

Ajoutez une nouvelle Android Application au projet en sélectionnant la zone illustrée dans l’image suivante.

Firebase : ajouter Firebase à une application Android

L’ajout d’une nouvelle Application se fait en 3 étapes.

Vous devez d’abord fournir un Android Package Name. Nous utilisons com.foo.playfab.app, mais veillez à choisir votre propre Package Name lorsque vous suivez ce tutoriel.
Sélectionnez le bouton Register App pour passer à l’étape suivante.

Firebase : inscrire l'application Android

L’étape 2 vous permet de télécharger un fichier de paramètres appelé google-services.json. Il sera utilisé ultérieurement dans l’App pour configurer automatiquement les services Google.

Après l’avoir téléchargé, sélectionnez le bouton Continue pour passer à l’étape suivante.

Firebase : ajouter le fichier de paramètres Google

La dernière étape fournit des informations sur la configuration de votre processus de build pour connecter les SDK Firebase et Google Play.

Vous pouvez ignorer ces informations, car nous utiliserons un outil automatisé intégré à Android Studio qui effectue cette configuration automatiquement.

Sélectionnez le bouton Finish pour continuer.

Firebase : terminer l'ajout à l'application Android

Une fois l’Application ajoutée, elle apparaît dans le tableau de bord.
À ce stade, la configuration est terminée et nous devons extraire la clé de serveur FCM (que nous utiliserons pour connecter les notifications push PlayFab).
Accédez aux Project settings, comme illustré dans l’image suivante.

Dans Project settings, accédez à l’onglet Cloud Messaging.
Repérez la zone Server Key (la zone rouge dans l’image ci-dessous).
Copiez cette Key et conservez-la en lieu sûr, à un endroit facilement accessible.

Firebase : Cloud Messaging, clé de serveur

À ce stade, nous avons fait tout ce qui est nécessaire dans Firebase pour activer les notifications push.

Chapitre 2 : configuration de la console Google Play

Lorsque votre application est prête, vous créerez très probablement un projet Google Console pour gérer la page produit du Play Store. Voyons comment créer un projet Google Play et le lier au projet Firebase. Commencez par accéder à la page de la console Google Play et créez un nouveau projet, comme illustré dans l’image suivante.

Attribuez le Title.

Dans cet exemple, nous utilisons Foo PlayFab App. Veillez à choisir votre propre titre et votre propre nom de package lorsque vous suivez ce tutoriel.

Sélectionnez le bouton Create pour continuer.

La page Google Play Console Project s’ouvre.
Sélectionnez Services & APIs dans le menu latéral.

La page Services configuration s’ouvre.
Repérez le panneau Firebase Cloud Messaging.
Sélectionnez le bouton Link a Sender ID, comme illustré dans l’image suivante.

Google Play : panneau FCM, lier un Sender ID

Pour lier le Sender ID :

Utilisez la clé de serveur FCM que vous avez obtenue (et enregistrée) dans la console Firebase au chapitre précédent.
Lorsque vous avez terminé, sélectionnez le bouton Link, comme illustré dans notre exemple.

Google Play : lier un Sender ID, ajouter la clé d'API FCM

Prenez un moment pour vérifier que le Sender ID affiché dans la Google Play Console correspond à celui de la Firebase Console, comme illustré dans l’exemple ci-dessous.

Console Google Play et console Firebase : correspondance du Sender ID

À ce stade, le Google Play Console Project est correctement lié au Firebase Project.

Chapitre 3 : configuration du titre PlayFab

L’objectif de ce chapitre est de vous montrer comment configurer les services PlayFab afin qu’ils puissent envoyer des notifications push au joueur en votre nom.

Vous devez d’abord accéder à Title settings dans le menu Settings de votre titre.
Sélectionnez l’onglet Push Notifications.
Pour l’option Android, sélectionnez l’icône Settings.

PlayFab : notifications push, paramètres Android

Votre Google server API key vous est demandée.
Copiez celle que vous avez obtenue au moyen de la console Firebase, comme illustré dans l’exemple ci-dessous.

PlayFab et console Firebase : ajouter la clé d'API serveur

Si tout est correct, une page indiquant que les Push Notifications sont Active s’affiche.

La configuration de votre titre PlayFab est terminée.

Chapitre 4 : configuration du projet Android Studio

Pour utiliser le JavaSDK PlayFab, vous aurez besoin du JavaSDK client PlayFab et de sa dépendance, Google GSON.

Téléchargez ici la bibliothèque JAR du JavaSDK client PlayFab.
Recherchez client-sdk-*.jar, ainsi que la documentation Java correspondante si nécessaire.
Téléchargez la dernière version de Google GSON.
Recherchez gson-*.jar.
Gardez à portée de main les fichiers .jar mentionnés ci-dessus.

Commencez par créer un projet Android Studio classique.

Vérifiez que le Package name correspond à celui que vous avez utilisé tout au long de ce tutoriel (dans Firebase, par exemple).

Pour les besoins de cet exemple, nous utilisons com.foo.playfab.app, mais n’oubliez pas de choisir votre propre nom de package et votre propre titre lorsque vous suivez ce tutoriel.

Android Studio : nouveau projet, ajouter le nom de l'application

Sélectionnez le Minimum SDK de votre choix.
Sélectionnez ensuite le bouton Next.

Android Studio : nouveau projet, sélectionner le SDK minimal

Pour ce tutoriel, nous vous suggérons de commencer avec le modèle Empty Activity.

Sélectionnez le modèle que vous souhaitez utiliser.
Sélectionnez ensuite le bouton Next.

Android Studio : nouveau projet, sélectionner un modèle

Configurez le modèle comme vous le souhaitez.
Sélectionnez le bouton Finish.

Android Studio : nouveau projet, terminer

Une fois le projet nouvellement créé ouvert :

Passez à l’onglet Project (1).

Au chapitre précédent, vous avez téléchargé le fichier de configuration google-services.json depuis la console Firebase. Utilisez-le pour l’étape suivante.

Vérifiez que ce fichier est placé dans le dossier App (2).
Accédez ensuite à Tools (3).
Sélectionnez Firebase (4), comme illustré dans l’exemple ci-dessous.

Android Studio : ajouter le fichier de configuration au projet

L’Firebase Assistant s’ouvre sur le côté droit de la fenêtre.

Repérez le dossier Cloud Messaging et sélectionnez Set up Firebase Cloud Messaging, comme illustré ci-dessous.

Android Studio : assistant Firebase, configurer Cloud Messaging

Dans le Firebase Notifications Assistant, sélectionnez le bouton Add FCM to your app (1), comme illustré dans l’image suivante.
Une boîte de dialogue s’ouvre, indiquant que de nouvelles dépendances seront ajoutées au moyen de Gradle.
Sélectionnez Accept Changes (2) pour accepter les modifications.

Malheureusement, les dépendances ajoutées automatiquement par le processus de synchronisation Gradle (3) sont incorrectes et provoqueront un échec!

Pour configurer correctement les dépendances, remplacez les lignes ajoutées automatiquement par les suivantes : implementation 'com.google.firebase:firebase-core:16.0.3
implementation 'com.google.firebase:firebase-messaging:17.0.0

Android Studio : assistant Firebase, ajouter FCM à votre application

Une fois ce processus terminé :

Vérifiez que le Firebase Notifications Assistant indique que les dépendances sont désormais correctement configurées (1).

Au début de ce chapitre, nous avons obtenu les fichiers JAR nécessaires. Normalement, le fichier de build récupère automatiquement ces fichiers.

Pour vous assurer que ces fichiers JAR sont répertoriés dans le dossier app/libs (2), sélectionnez tous les fichiers et cliquez dessus avec le bouton droit.
Choisissez ensuite Add as library… (3), comme illustré dans l’exemple ci-dessous.

Android Studio : assistant Firebase, ajouter en tant que bibliothèque

À l’aide du générateur d’icônes de notification d’Android Asset Studio, préparez les icônes et placez-les dans app/src/main/res.
Dans l’exemple ci-dessous, l’icône s’appelle ic_stat_blur_on.

Enfin, sélectionnez Rebuild Project.

Nous pouvons maintenant commencer à implémenter le code de réception et de gestion des notifications. Nous allons modifier (et créer si nécessaire) 4 fichiers :

app/src/main/AndroidManifest.xml
app/src/main/java/..packagePath../MainActivity.java
app/src/main/java/..packagePath../FooAppFirebaseInstanceIdService.java
app/src/main/java/..packagePath../FooAppFirebaseMessagingService.java

L’implémentation actuelle est conçue pour être aussi courte que possible, uniquement pour tester rapidement les notifications. Consultez les guides FCM pour connaître les pratiques exemplaires de qualité et des exemples d’implémentation plus complexes.

AndroidManifest.xml

Dans le code suivant, remplacez tous les espaces réservés MY_PACKAGE_IDENTIFIER par votre propre identifiant de package.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="MY_PACKAGE_IDENTIFIER">
    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- The following block enables our custom Firebase Instance ID Service-->
        <service android:name=".FooAppFirebaseInstanceIdService" android:exported="true">
            <intent-filter>
                <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
            </intent-filter>
        </service>

        <service
            android:name=".FooAppFirebaseMessagingService" android:exported="true">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT"/>
            </intent-filter>
        </service>

    </application>

</manifest>

MainActivity.java

Les espaces réservés suivants du code doivent être remplacés en fonction de votre scénario.

PLAYFAB_TITLE_ID
- Utilisez l’ID de votre titre obtenu dans PlayFab Game Manager.
PACKAGE_IDENTIFIER
- Utilisez l’identifiant de package Java correspondant à votre configuration.

package PACKAGE_IDENTIFIER;

import android.os.AsyncTask;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;
import com.playfab.PlayFabClientAPI;
import com.playfab.PlayFabClientModels.*;
import com.playfab.PlayFabErrors;
import com.playfab.PlayFabSettings;
import java.util.List;
import java.util.Map;

public class MainActivity extends AppCompatActivity {

    // Invoked when activity is started
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Set PlayFab title
        PlayFabSettings.TitleId = "PLAYFAB_TITLE_ID";

        // Start login operation
        AsyncTask.execute(new Runnable() {
            @Override
            public void run() {
                if(login()) FooAppFirebaseInstanceIdService.setAllowRegisterForPush(true); // Ready to register for push notifications
            }
        });
    }

    public boolean login(){
        LoginWithAndroidDeviceIDRequest request = new LoginWithAndroidDeviceIDRequest();
        request.CreateAccount = true;

        // There are several approaches on getting unique android device id.
        // https://stackoverflow.com/questions/2785485/is-there-a-unique-android-device-id
        request.AndroidDeviceId = "qwerty";

        PlayFabErrors.PlayFabResult<LoginResult> response = PlayFabClientAPI.LoginWithAndroidDeviceID(request);
        if(response.Error != null){
            Log.d("Foo PlayFab App",CompileErrorsFromResult(response.Error));
            return false;
        }
        return true;
    }

    // Utility method to compose an error message out of PlayFab result.
    private static String CompileErrorsFromResult(PlayFabErrors.PlayFabError error) {
        if (error == null)
            return null;

        String errorMessage = "";
        if (error.errorMessage != null)
            errorMessage += error.errorMessage;
        if (error.errorDetails != null)
            for (Map.Entry<String, List<String>> pair : error.errorDetails.entrySet())
                for (String msg : pair.getValue())
                    errorMessage += "\n" + pair.getKey() + ": " + msg;
        return errorMessage;
    }
}

FooAppFirebaseInstanceIdService.java

L’espace réservé du code ci-dessous doit être remplacé en fonction de votre scénario.

PACKAGE_IDENTIFIER
- L’identifiant de package Java correspondant à votre configuration.

package PACKAGE_IDENTIFIER;

import android.text.TextUtils;
import android.util.Log;
import com.google.firebase.iid.FirebaseInstanceId;
import com.google.firebase.iid.FirebaseInstanceIdService;
import com.playfab.PlayFabClientAPI;
import com.playfab.PlayFabClientModels;
import com.playfab.PlayFabErrors;
import java.util.List;
import java.util.Map;

public class FooAppFirebaseInstanceIdService extends FirebaseInstanceIdService {

    private static String _token;

    private static boolean _allowRegistration;

    // This is invoked from activity that performs authentication.
    // Once login is complete this method is invoked.
    // If we have a pending token, we use it to register for push notifications
    public static void setAllowRegisterForPush(boolean isAllowed) {
        _allowRegistration = isAllowed;
        if (_allowRegistration && !TextUtils.isEmpty(_token)) {
            registerForPush(_token);
        }
    }

    // Invoked when firebase has fetched a token
    // If we already have logged in, we use new token to register for push
    @Override
    public void onTokenRefresh() {
        _token = FirebaseInstanceId.getInstance().getToken();
        if (_allowRegistration && !TextUtils.isEmpty(_token)) {
            registerForPush(_token);
        }
    }

    private static void registerForPush(String token) {
        PlayFabClientModels.AndroidDevicePushNotificationRegistrationRequest request = new PlayFabClientModels.AndroidDevicePushNotificationRegistrationRequest();
        request.DeviceToken = token;

        PlayFabErrors.PlayFabResult<PlayFabClientModels.AndroidDevicePushNotificationRegistrationResult> response = PlayFabClientAPI.AndroidDevicePushNotificationRegistration(request);

        if (response.Error != null) {
            Log.d("Foo PlayFab App", CompileErrorsFromResult(response.Error));
        }
    }

    // Utility method to compose an error message out of PlayFab result.
    private static String CompileErrorsFromResult(PlayFabErrors.PlayFabError error) {
        if (error == null)
            return null;

        String errorMessage = "";
        if (error.errorMessage != null)
            errorMessage += error.errorMessage;
        if (error.errorDetails != null)
            for (Map.Entry<String, List<String>> pair : error.errorDetails.entrySet())
                for (String msg : pair.getValue())
                    errorMessage += "\n" + pair.getKey() + ": " + msg;
        return errorMessage;
    }

}

FooAppFirebaseMessagingService.java

L’espace réservé du code ci-dessous doit être remplacé en fonction de votre scénario.

PACKAGE_IDENTIFIER
- L’identifiant de package Java correspondant à votre configuration.

package com.foo.playfab.app;

import android.util.Log;
import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;

public class FooAppFirebaseMessagingService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(RemoteMessage message) {
        // Intercept the message here
        Log.d("Foo PlayFab App","Message received: "+message.getNotification().getBody());
    }
}

Test

À ce stade, vous devriez pouvoir déployer l’application sur l’appareil.

Une fois l’application démarrée, elle se connecte automatiquement et s’inscrit aux notifications push.
Sélectionnez le bouton Home de votre appareil pour réduire l’application. C’est important, car cela nous permet de tester la notification qui arrive dans la barre d’état système.
Accédez ensuite à la page Game Manager de votre titre PlayFab et utilisez le tableau de bord pour repérer la dernière Push Registration.
Sélectionnez le Player ID (1).

PlayFab : PlayStream, journal des événements

Une page Send Push Notification s’ouvre pour ce joueur.

Sélectionnez le bouton Send Push Notification (1).
Saisissez le Title (2).
Entrez le corps de votre message (3).
Validez vos modifications en sélectionnant le bouton Send Push Notification (4).

Vérifiez que le message arrive sur votre appareil.

Application Android : réception d'une notification push PlayFab

Si votre message arrive, les messages sont correctement distribués dans votre application. À ce stade, l’intégration est réussie. Vous pouvez utiliser FooAppFirebaseMessagingService pour gérer le message entrant pendant l’exécution de votre application.

​Vue d’ensemble

​1. Google Play Services

​2. Firebase Cloud Messaging (FCM)

​3. Services PlayFab

​4. Services clients

​Répartition en quatre parties

​Prérequis

​Scénario

​Chapitre 1 : configuration de Firebase

​Chapitre 2 : configuration de la console Google Play

​Chapitre 3 : configuration du titre PlayFab

​Chapitre 4 : configuration du projet Android Studio

​AndroidManifest.xml

​MainActivity.java

​FooAppFirebaseInstanceIdService.java

​FooAppFirebaseMessagingService.java

​Test

Vue d’ensemble

1. Google Play Services

2. Firebase Cloud Messaging (FCM)

3. Services PlayFab

4. Services clients

Répartition en quatre parties

Prérequis

Scénario

Chapitre 1 : configuration de Firebase

Chapitre 2 : configuration de la console Google Play

Chapitre 3 : configuration du titre PlayFab

Chapitre 4 : configuration du projet Android Studio

AndroidManifest.xml

MainActivity.java

FooAppFirebaseInstanceIdService.java

FooAppFirebaseMessagingService.java

Test