Avec la croissance rapide de la RA, de la RV et de l’apprentissage basé sur les jeux, on me demande fréquemment: «Comment puis-je envoyer des relevés xAPI depuis Unity?» J’ai toujours répondu en pointant l’interlocuteur vers GBLxAPI.org. Autant que je sache, c’est la seule bibliothèque xAPI développée spécifiquement pour Unity. Étant donné que beaucoup de mes clients ont commencé à développer dans Unity, j’ai pensé que je devrais étudier moi-même la bibliothèque GBLxAPI.
Tout d’abord, quelques avertissements:
- J’ai très peu d’expérience avec Unity. Si vous recherchez un guide étape par étape sur Unity, visitez Learn.Unity.com. C’est ce que j’ai fait.
- Pour les besoins de cet article, je suppose que vous avez une connaissance pratique de xAPI.
- Cet article est assez technique. Le développement dans Unity nécessite non seulement la connaissance de Unity lui-même, mais également du langage de programmation c #. Il est difficile de vous montrer comment ajouter xAPI à Unity sans vous montrer du code c #.
- Mes exemples ont été créés à l’aide d’une pré-version de la version 1.1 de la bibliothèque GBLxAPI. Il devrait être disponible au moment de la publication de cet article. Certaines choses peuvent avoir changé par rapport à la version préliminaire.
Encore avec moi? Excellent, commençons.
Étape 1 – Créez un jeu dans Unity
Si vous avez déjà un jeu dans Unity, vous pouvez passer à l’étape 2. Je n’avais pas de jeu, j’ai donc suivi l’exemple Roll-A-Ball que j’ai trouvé sur Learn.Unity.com. J’ai ensuite ajouté une scène «Connexion» afin que je puisse collecter le nom du joueur à utiliser dans les déclarations xAPI. J’ai créé un deuxième niveau et ajouté une minuterie pour que je puisse dire combien de temps il a fallu pour terminer le jeu. Enfin, j’ai ajouté de la musique dramatique (gratuite) et voilà, j’avais un jeu. (Figure 1)
Figure 1: Le jeu Roll-A-Ball de Learn.Unity.com
Étape 2 – Obtenez la bibliothèque GBLxAPI
Maintenant que vous avez un jeu Unity, rendez-vous sur GBLxAPI.org et inscrivez-vous à la bibliothèque. Il est gratuit et vous pouvez le télécharger immédiatement. Je suggère de télécharger et de décompresser la bibliothèque dans son propre dossier. J’ai habilement appelé mon dossier «GBLxAPI».
Il existe un article de blog sur la mise en route de GBLxAPI situé ici. Malheureusement, la section «Configuration» est incomplète et manque quelques étapes. Voici ce qu’il oublie de vous dire:
- L’étape 5 de l’article du blog vous explique comment ajouter vos propres verbes xAPI, types d’activités, etc.
- Les instructions ne mentionnent pas non plus que vous devez copier le fichier «GBL_Interface.cs» dans le dossier Assets / Scripts de votre jeu.
Étape 3 – Configurez votre vocabulaire
La bibliothèque GBLxAPI est fournie avec un vocabulaire xAPI intégré. Les verbes, les types d’activités, etc. sont définis dans un fichier de vocabulaire par défaut. Vous pouvez ajouter ou remplacer le vocabulaire par défaut avec vos propres verbes, types d’activités et autres éléments de vocabulaire. La façon dont cela est censé fonctionner est que vous éditez un fichier Microsoft Excel, puis exécutez un programme Python pour générer les fichiers JSON réellement utilisés par GBLxAPI. Bien que Python soit installé dans mon environnement de développement, le processus n’a pas fonctionné. Aucun fichier n’a été généré et je n’ai reçu aucune erreur.
La solution est que vous pouvez modifier le fichier JSON directement, en contournant le programme Python. Le fichier est nommé «GBLxAPI_Vocab_User.json» et se trouve sous Assets / Resources / data. Voici un fichier d’exemple (Extrait 1):
{
"action": {},
"activity": {},
"domain": {},
"extension": {},
"focus": {},
"grade": {},
"skills": {},
"subdomain": {},
"topic": {},
"verb": {
"completed": {
"description": { "en-US": "" },
"id": "http://adlnet.gov/expapi/verbs/completed",
"name": { "en-US": "completed" }
},
"satisfied": {
"description": { "en-US": "" },
"id": "https://w3id.org/xapi/adl/verbs/satisfied",
"name": { "en-US": "satisfied" }
}
}
}
Extrait 1
Premièrement, je remplace le verbe «terminé» utilisé par GBLxAPI. L’identifiant de verbe que la bibliothèque utilise par défaut n’est pas celui que je souhaite utiliser. Je le remplace donc par un qui me semble plus approprié pour mon jeu.
Deuxièmement, j’ai ajouté le verbe «satisfait». Lorsque mon joueur de jeu termine les deux niveaux, j’envoie une déclaration avec le verbe «satisfait».
Étape 4 – Initialisation de GBLxAPI
Ouvrez le fichier «Assets / GBLXAPI / Scripts / GBLConfig.cs». Près du sommet, vous trouverez les propriétés suivantes. (Extrait 2)
public const string LrsURL = “YOUR LRS ENDPOINT”;
public const string companyURI = “YOUR HOME PAGE FOR ACTORS”;
public const string gameURI = “YOUR GAME IRI”;
public const string gameName = “YOUR GAME NAME”;
Extrait 2
Modifiez les valeurs comme suit:
- LrsURL
C’est le point final du LRS qui recevra vos relevés. - gameURI
Il s’agit de l’identifiant unique de votre jeu. Il doit s’agir d’un IRI (International Resource Identifier). - gameName
Le nom de votre jeu. - companyURI
Cette valeur est utilisée comme propriété «page d’accueil» pour les acteurs xAPI.
Rendez-vous maintenant sur Assets / Scripts / GBL_Interface.cs. Ici, vous devez définir les propriétés suivantes:
- lrsUser
L’ID utilisateur ou la clé requis pour écrire des instructions dans votre LRS. - lrsPassword
Le mot de passe requis pour écrire des déclarations dans votre LRS.
Une fois ces propriétés définies, vous êtes prêt à initialiser GBLxAPI. Quelque part dans votre code c #, avant d’essayer d’envoyer des instructions, vous avez besoin du code suivant: (Extrait 3)
GBLXAPI.Init(new GBLConfig(GBL_Interface.lrsUser, GBL_Interface.lrsPassword));
Extrait 3
Examinons ensuite quelques propriétés que j’utiliserai pour simplifier le code à l’étape suivante. (Extrait 4)
private static Agent playerAsAgent
{
get
{
return GBLXAPI.Agent
.WithUUID(NameTransfer.playerName)
.WithHomePage(GBLXAPI.Configuration.companyURI)
.Build();
}
}
private static Activity MainGameActivity
{
get
{
return GBLXAPI.Activity
.WithID(GBLXAPI.Configuration.gameURI)
.WithDefinition(GBLXAPI.ActivityDefinition
.WithType("serious-game")
.WithName(GBLXAPI.Configuration.gameName)
.Build())
.Build();
}
}
Extrait 4
La propriété playerAsAgent renvoie un agent utilisant l’un des «générateurs» de GBLxAPI. J’utilise les méthodes de création pour utiliser le nom du joueur. J’ai également défini la page d’accueil du lecteur. N’oubliez pas que nous avons défini la propriété «companyURI» plus tôt dans GBLConfig.cs. GBLxAPI prend également en charge l’utilisation de la méthode «mbox» d’identification d’un acteur xAPI. Remarque: Dans le code ci-dessus, «NameTransfer» est un objet statique que j’utilise pour stocker des informations sur le lecteur.
Étant donné que toutes mes déclarations utiliseront le jeu lui-même comme une activité, je crée une propriété MainGameActivity.
Ensuite, je souhaite utiliser des minuteries pour chaque niveau afin de pouvoir inclure une durée sur mes instructions xAPI. Avant d’utiliser GBLxAPI, j’avais créé mes propres minuteries à cet effet. Mais avec GBLxAPI, je peux utiliser les créneaux horaires intégrés. Donc, dans la méthode Start () d’un niveau, j’ai ce qui suit: (Extrait 5)
// Start a timer for this level.
GBLXAPI.Timers.ResetSlot((int)GBL_Interface.durationSlots.Level);
Extrait 6
Vous récupérez le temps écoulé comme suit:
timeElapsed = GBLXAPI.Timers.GetSlot((int)GBL_Interface.durationSlots.Level);
Étape 5 – Envoyez une déclaration
Lorsqu’un joueur termine un niveau, je veux envoyer une déclaration «terminé» avec la durée passée sur le niveau. Voici ma fonction pour faire cela en utilisant GBLxAPI: (Extrait 7)
protected void SendxAPILevelComplete(string sceneName, int level, TimeSpan duration)
{
// I want to control the name of the "object", so I create an ActivityDefinition
var activityDef = new ActivityDefinition
{
name = new LanguageMap()
};
activityDef.name.Add("en-US", sceneName);
GBLXAPI.Statement
.WithActor(playerAsAgent)
.WithVerb("completed")
.WithTargetActivity(GBLXAPI.Activity
.WithID(GBLXAPI.Configuration.gameURI + "/level/" + level)
.WithType("level")
.WithDefinition(activityDef)
.Build())
.WithResult(GBLXAPI.Result
.WithDuration((float)duration.TotalSeconds)
.Complete()
.Build())
.WithContext(GBLXAPI.Context
.WithParents( new List
{
MainGameActivity // The game itself is parent of a level
})
.Build())
.Enqueue(GBLxAPICallBackHandler);
}
Extrait 7
Tout d’abord, je crée une définition d’activité pour mon objet. Ce n’est pas obligatoire, mais je souhaite contrôler le nom de mon objet.
Ensuite, j’appelle le générateur d’instructions GBLxAPI. J’ajoute l’acteur en utilisant ma propriété playerAsAgent évoquée précédemment, puis le verbe. L’objet cible est le niveau complété par le joueur. J’utilise le générateur de résultats pour ajouter la durée passée sur le niveau et indiquer que le niveau est terminé. Je fais ensuite du jeu lui-même une activité de contexte parent pour la déclaration.
Enfin, j’appelle la méthode Enqueue de GBLxAPI pour envoyer la déclaration. J’utilise un gestionnaire de rappel comme paramètre pour Enqueue car je garde un décompte des déclarations envoyées et je les affiche dans mon jeu. (Extrait 7)
public void GBLxAPICallBackHandler(bool result, string resultText)
{
if (result)
{
// Statement was successful
StatementsSent++;
countText.text = "Statements Sent: " + StatementsSent;
return;
}
Debug.Log("Sending statement failed: " + resultText);
}
Extrait 8
Avantages et inconvénients de GBLxAPI
Commençons par les «avantages» de l’utilisation de GBLxAPI.
- Comme vous pouvez le voir, le code que j’ai dû écrire pour envoyer une déclaration est assez court. Je l’ai littéralement fait fonctionner en une heure environ.
- Il est livré avec le code source, vous pouvez donc ajouter des méthodes supplémentaires dont vous pourriez avoir besoin. Par exemple, j’ajouterais la possibilité de créer un acteur en utilisant l’adresse e-mail du joueur. Ou contribuez à la communauté en proposant du code sur le site GitHub.
- La méthode «Enqueue» met en cache les déclarations si le joueur n’est pas connecté à Internet, puis les envoie lorsque le joueur est de nouveau en ligne. C’est plutôt cool!
- La bibliothèque a été récemment mise à jour, il est donc bon de savoir qu’elle est en cours de maintenance.
Voyons maintenant les «inconvénients» de l’utilisation de GBLxAPI.
- La méthode d’utilisation de Microsoft Excel pour modifier le vocabulaire ne semble pas fonctionner. La solution de contournement consiste simplement à modifier directement le JSON.
- GBLxAPI traite uniquement la partie API de l’instruction de xAPI. Il n’existe aucune méthode pour utiliser les API d’état, de profil d’agent ou de profil d’activité.
- Je suis un peu préoccupé par le fait qu’elle s’appelle toujours une bibliothèque «bêta». Autant que je sache, il est sorti en 2018. C’est un cycle bêta assez long. D’autre part, vous obtenez le code source afin de pouvoir le modifier facilement si vous rencontrez des problèmes.
Alternatives à GBLxAPI
Puisque je connais maintenant un peu Unity, je sais qu’il utilise c # comme langage de programmation. Cela signifie que la bibliothèque open-source TinCan.Net peut être utilisée. En fait, en explorant GBLxAPI, j’ai découvert qu’il utilisait TinCan.Net. Si vous avez besoin d’écrire dans l’API State, vous pouvez utiliser TinCan.Net. D’un autre côté, si vous cherchez à envoyer des instructions xAPI depuis Unity et que vous voulez quelque chose de rapide et simple, essayez GBLxAPI.
