Invitations à un jeu

Les invitations à un jeu permettent aux joueur·ses d’inviter leurs ami·es à jouer à un jeu. L’invitation est envoyée par un·e joueur·se à un·e ou plusieurs de ses ami·es, et s’accompagne toujours d’un appel à l’action relatif au jeu. Les destinataires peuvent être des joueur·ses existant·es, ou nouvelles ou nouveaux.

Les invitations à un jeu peuvent servir à attirer de nouveaux joueurs ou nouvelles joueuses ou à relancer des joueur·ses existant·es. Les invitations peuvent être envoyées dans deux cas de figure :

1. Le ou la destinataire est un·e ami·e de l’expéditeur·ice et ne s’est pas authentifié·e dans le jeu. L’envoi d’une invitation convient parfaitement dans ce cas de figure.
2. Le ou la destinataire est un·e ami·e de l’expéditeur·ice et s’est déjà authentifié·e dans le jeu. L’envoi d’une notification de tour de jeu et d’une demande d’aide convient parfaitement dans ce cas de figure.

Les invitations sont envoyées lorsque l’expéditeur·ice est dans le jeu et les destinataires les reçoivent à différents endroits sur Facebook. Les invitations sont toujours privées et seul·e le ou la destinataire peut les voir. Une invitation peut être envoyée à plusieurs destinataires à la fois, mais un·e destinataire peut uniquement consulter les détails de l’expéditeur·ice, pas ceux des autres destinataires de l’invitation.

Exemple d’invitation à un jeu sur Facebook, sur ordinateur.

Les invitations à un jeu sont compatibles avec les jeux sur Facebook et les jeux pour mobile sur iOS et Android. Sur le site Facebook pour ordinateur, les invitations apparaissent sous la forme d’une notification sonore en bas à gauche de l’écran ainsi que dans les notifications, si elles ne sont pas filtrées. Sur les plateformes mobiles, elles apparaissent dans la liste des notifications de l’application Facebook, si elles ne sont pas filtrées. Les données des invitations sont accessibles par le biais de l’API Game Request, et vous pouvez créer des éléments d’interface personnalisés pour une meilleure intégration au sein des jeux pour mobile. Veillez donc à ce que vos invitations soient parfaitement implémentées sur l’ensemble des plateformes de manière à proposer une expérience d’utilisation cohérente. Cependant, les invitations envoyées par le joueur ou la joueuse apparaissent sur toute combinaison de plateformes prises en charge par votre jeu.

Lancement de la boîte de dialogue d’invitation

La boîte de dialogue d’invitation à un jeu est générée par le biais du SDK pour JavaScript, iOS, Android et Unity. Dans ces exemples, nous partons du principe que l’expéditeur·ice s’est déjà authentifié·e dans l’application. Si aucun·e destinataire n’est indiqué·e, vous pouvez sélectionner jusqu’à 50 personnes dans votre liste d’ami·es, et choisir d’afficher uniquement les joueur·ses déjà enregistré·es ou les ami·es non enregistré·es. Ce filtre est très utile pour distinguer les personnes qu’il faut relancer ou inviter à jouer au jeu.

JavaScript

Envoi d’invitations à l’aide du sélecteur multi-ami·es fourni par la boîte de dialogue d’invitation à un jeu :

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE'
}, function(response){
  console.log(response);
});

Une fois la boîte de dialogue fermée, l’objet response contiendra les résultats de l’envoi, y compris un ID request et une liste de destinataires to. Par exemple :

{
  "request":"1428237347457728",
  "to":["10150002163885335"]
}

Par défaut, un sélecteur multi-ami·es apparaît à l’écran et permet à l’expéditeur·ice de sélectionner jusqu’à 50 destinataires.

Envoi d’invitations à un·e destinataire en particulier :

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID'
}, function(response){
  console.log(response);
});

Si le champ to a été précisé, l’expéditeur·ice ne peut pas sélectionner d’autres destinataires.

Envoi d’invitations à plusieurs destinataires en particulier :

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID, USER_ID, USER_ID'
}, function(response){
  console.log(response);
});

Plusieurs destinataires peuvent être précisé·es via une liste des ID utilisateur séparés par des virgules.

Envoi d’invitations à des listes d’ami·es en particulier :

FB.ui({method: 'apprequests',
  message: 'Friend Smash Request!',
  filters: [{name:'GROUP_1_NAME', user_ids:['USER_ID','USER_ID','USER_ID']},{name:'GROUP_2_NAME', user_ids: ['USER_ID','USER_ID','USER_ID']}]
}, function(response){
  console.log(response);
}});

Envoi d’objets par le biais d’invitations en indiquant de manière explicite les paramètres action_type et object_id :

FB.ui({method: 'apprequests',
  message: 'Take this bomb to blast your way to victory!',
  to: {user-ids},
  action_type:'send',
  object_id: 'YOUR_OBJECT_ID'  // e.g. '191181717736427'
}, function(response){
  console.log(response);
});

Ne précisez aucun object_id pour les invitations informant une personne que c’est à son tour de jouer.

FB.ui({method: 'apprequests',
  message: 'Just smashed you 78 times! It\'s your turn.',
  to: {user-ids},
  action_type:'turn'
}, function(response){
  console.log(response);
});

Les destinataires peuvent également être placé·es dans des listes nommées, ce qui permet au joueur ou à la joueuse de faire son choix parmi des ami·es regroupé·es selon une certaine logique, en fonction de leur statut dans le jeu.

Pour en savoir plus, consultez la documentation de référence FB.ui concernant le SDK Facebook pour JavaScript.

SDK pour iOS

Lancement de la boîte de dialogue d’invitation à un jeu à l’aide du sélecteur d’ami·es fourni par le SDK pour iOS :

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
// Look at FBSDKGameRequestContent for futher optional properties
gameRequestContent.message = @"YOUR_MESSAGE_HERE";
gameRequestContent.title = @"OPTIONAL TITLE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

Envoi d’invitations indiquant de manière explicite un action_type et un object_id à un·e destinataire en particulier au moyen du SDK iOS :

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
gameRequestContent.message = @"Take this bomb to blast your way to victory!";
gameRequestContent.to = @[@"RECIPIENT_USER_ID"];
gameRequestContent.objectID = @"YOUR_OBJECT_ID";
gameRequestContent.actionType = @"ACTION_TYPE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

SDK pour Android

Envoi d’une invitation à l’aide du sélecteur d’ami·es de la boîte de dialogue d’invitation à un jeu au moyen du SDK pour Android :

GameRequestDialog requestDialog;
CallbackManager callbackManager;

public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  FacebookSdk.sdkInitialize(this.getApplicationContext());
  callbackManager = CallbackManager.Factory.create();
  requestDialog = new GameRequestDialog(this);
  requestDialog.registerCallback(callbackManager,
    new FacebookCallback<GameRequestDialog.Result>() {
    public void onSuccess(GameRequestDialog.Result result) {
      String id = result.getId();
    }
    public void onCancel() {}
      public void onError(FacebookException error) {}
    }
  );
}

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .build();
  requestDialog.show(content);
}

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  callbackManager.onActivityResult(requestCode, resultCode, data);
}

Envoi d’une invitation indiquant de manière explicite une action et un objet au moyen du SDK pour Android :

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .setTo("USER_ID")
    .setActionType(ActionType.SEND)
    .setObjectId("YOUR_OBJECT_ID")
    .build();
  requestDialog.show(content);
}

SDK pour Unity

Voici comment les demandes sont envoyées avec le SDK pour Unity. Consultez la documentation FB.AppRequest pour en savoir plus.

FB.AppRequest(
  message: "I Just got " + GameStateManager.Score.ToString() + " points! Can you beat it?",
  to: recipients,
  data: "{\"challenge_score\":" + GameStateManager.Score.ToString() + "}"
  title: "Friend Smash Challenge!",
  callback:appRequestCallback
);

Paramètres de la boîte de dialogue

Lors de la création de la boîte de dialogue d’invitation à un jeu, il est possible de définir plusieurs paramètres supplémentaires servant à en déterminer le comportement. Vous trouverez une description de ces paramètres ci-dessous.

Données de réponse

Lorsqu’une invitation a été envoyée par l’intermédiaire de la boîte de dialogue d’invitation à un jeu, une réponse est transférée au rappel et contient les informations suivantes :

Gestion des invitations dans le jeu

Acceptation des invitations

Lorsqu’un·e destinataire accepte une invitation sur le site Facebook pour ordinateur, il ou elle est redirigé·e vers l’URL du jeu qui a envoyé l’invitation. Cette URL contient un paramètre GETrequest_ids supplémentaire. Il s’agit d’une liste des ID des invitations délimitée par des virgules et que l’utilisateur·ice accepte :

http://apps.facebook.com/[app_name]/?request_ids=[REQUEST_IDs]

Les invitations ne sont pas automatiquement supprimées lorsque le ou la destinataire les accepte. Votre jeu doit s’en charger. L’approche la plus courante consiste à lire à partir de l’API Graph la liste des invitations non traitées envoyées à cet·te utilisateur·ice une fois votre jeu lancé, et à les supprimer une à une dès qu’elles ont été traitées.

Lorsqu’un·e destinataire accepte une invitation sur une plateforme mobile, il ou elle est redirigé·e vers l’application au moyen d’un lien profond. Un paramètre supplémentaire sera présent lors du chargement de l’application : l’ID de l’invitation. Tout comme sur ordinateur, votre jeu doit se charger de supprimer les invitations acceptées sur appareil mobile. Nous vous recommandons de vérifier les invitations en attente et de les supprimer au lancement du jeu.

Lecture des invitations

Chaque invitation envoyée contient un ID d’objet d’invitation distinct. Cet ID représente l’objet de l’invitation. Celui-ci peut être concaténé avec l’ID utilisateur d’un·e destinataire pour créer une instance particulière de l’invitation. Cela représente une instanciation de l’invitation, qui a été envoyée à un·e destinataire en particulier.

Par exemple, lors de l’envoi d’une invitation, la réponse de la boîte de dialogue d’invitation à un jeu ressemble à ce qui suit :

{
  request: 'REQUEST_OBJECT_ID'
  to:[array of USER_IDs]
}

Si vous recherchez l’ID d’objet de l’invitation par le biais de l’API Graph, la réponse obtenue n’est pas exactement la même selon le contexte d’affichage de la recherche, mais elle représente toujours l’objet complet de l’invitation.

Par exemple, si une requête vers http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN est envoyée avec le token d’accès utilisateur du ou de la destinataire, vous obtiendrez la réponse suivante :

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

Notez que les champs to et from sont renvoyés. Toutefois, si le même point de terminaison est appelé à l’aide du token d’accès de l’expéditeur·ice ou d’un token d’accès d’application, Facebook renverra la réponse suivante :

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

Pour obtenir l’invitation complète qui inclut le ou la destinataire à l’aide d’un token d’accès d’application, vous devez ajouter l’ID utilisateur du ou de la destinataire, précédé d’un trait de soulignement « _ ». Par exemple, un appel vers https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} renvoie :

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

Lecture de toutes les invitations

Afin de lire toutes les invitations pour un·e destinataire, vous pouvez interroger le graphe comme indiqué ci-dessous à l’aide du USER ACCESS TOKEN du ou de la destinataire. Cette opération permet de renvoyer une liste des ID des invitations pour cet·te utilisateur·ice dans l’application.

GET https://graph.facebook.com/me/apprequests?access_token=[USER ACCESS TOKEN]

Suppression des invitations

Les invitations à un jeu ne sont pas automatiquement supprimées une fois que le ou la destinataire les a acceptées. Cette tâche revient au développeur ou à la développeuse. Vous devez supprimer les invitations au nom des joueur·ses après qu’elles ont été acceptées.

Il existe plusieurs façons de supprimer une invitation :

API Graph

Lancez une requête HTTP DELETE pour le paramètre request_id concaténé :

DELETE https://graph.facebook.com/[{REQUEST_OBJECT_ID}_{USER_ID}]?
      access_token=[USER or APP ACCESS TOKEN]

JavaScript

function deleteRequest(requestId) {
  FB.api(requestId, 'delete', function(response) {
    console.log(response);
  });
}

Suivi des invitations pour les recommandations et les récompenses

Vous pouvez récompenser l’expéditeur·ice de l’invitation à un jeu si le ou la destinataire a réalisé certaines actions particulières suite à l’envoi de cette invitation. Vous ne pouvez pas récompenser les joueur·ses qui ont simplement envoyé des invitations. En revanche, si le ou la destinataire installe le jeu et atteint un certain niveau après avoir accepté l’invitation, vous pouvez récompenser l’expéditeur·ice.

Pour offrir une récompense à l’expéditeur·ice, il faut d’abord savoir qui récompenser. Pour ce faire, vous disposez de deux méthodes :

1. Lors de l’envoi de l’invitation, stockez le request_id renvoyé dans la réponse de la boîte de dialogue d’invitation à un jeu et associez-le dès sa réception pour récompenser l’expéditeur·ice.
2. Lisez toutes les invitations envoyées à un·e joueur·se après qu’il ou elle a lancé le jeu, et récompensez l’expéditeur·ice en l’identifiant grâce à l’id figurant dans le champ from de ses invitations. Si plusieurs ami·es ont invité un·e joueur·se, vous pouvez choisir de ne récompenser que le premier expéditeur ou la première expéditrice, ou de récompenser tout le monde.

API Invitable Friends

Localisation

Pour vous aider à proposer la meilleure expérience d’utilisation possible à votre audience internationale, Facebook prend en charge la localisation des requests. Avant de traduire les invitations, il est essentiel que vous en connaissiez les différents types et compreniez la façon dont elles apparaissent à l’écran. Il existe des invitations standard comme « Anita vous a envoyé une invitation », ou, si une interaction action/objet est précisée, « Anita vous a demandé une vie » ou « Anita vous a envoyé une bombe ». Il existe également une invitation qui informe une personne que c’est à son tour de jouer dans une partie qui l’oppose à un·e ami·e. Tous ces exemples apparaissent à l’écran des joueur·ses qui se sont authentifié·es dans le jeu. Si le ou la destinataire n’a pas installé le jeu, il ou elle voit la demande sous la forme d’une invitation. Par exemple, « Anita vous a invité à jouer à Friend Smash! ». Voyons maintenant comment traduire chacune de ces invitations.

Traduction des invitations

Facebook traduit automatiquement le texte d’une invitation et les développeur·ses ne peuvent pas le modifier. La traduction s’effectue dans la langue du ou de la destinataire.

Notification d’invitation en anglais

Notification d’invitation en thaï

Notez que le texte « invited you to play » (vous a invité à jouer) affiché ci-dessus est automatiquement traduit dans l’autre langue, en thaï dans le cas présent. Le nom et la description de l’application sont traduits dans les cases jaunes ci-dessous, sous Nom à l’écran et Description de la section Localisation des paramètres de l’application.

Traduction du nom à l’écran et de la description de l’application

Les invitations peuvent également apparaître dans l’Espace Apps. L’Espace Apps affiche le « message » de l’invitation, qui peut être traduit par le ou la développeur·se. Dans les exemples ci-dessous, on peut voir que le message « Can I have a life to help me through the next level? » (Peux-tu me donner une vie pour que je réussisse le niveau suivant ?) en anglais a été traduit par « ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า » en thaï. À l’heure actuelle, le texte principal de l’invitation « Anita sent you a request » (Anita vous a envoyé une invitation) n’apparaît pas dans l’Espace Apps.

Invitation dans l’Espace Apps en anglais

Invitation dans l’Espace Apps en thaï

Traduction du message

Étant donné que le message est transféré en tant que paramètre lors de l’invocation de la boîte de dialogue d’invitation, vous pouvez le traduire vous-même avant d’invoquer la boîte de dialogue et transférer la chaîne traduite en tant que message. Si vous souhaitez modifier la traduction de manière dynamique, vous devez le faire avant d’invoquer la boîte de dialogue. Vous seul·e choisissez la langue qui s’affichera à l’écran, mais gardez à l’esprit que le texte apparaissant dans l’aperçu de l’invitation côté expéditeur·ice est identique à celui que le ou la destinataire verra lors de la réception de l’invitation.

Un grand nombre de développeur·ses identifient la langue de l’expéditeur·ice et se basent sur cette information pour déterminer la langue à utiliser pour le message. Ils ou elles partent du principe que dans la plupart des cas, l’expéditeur·ice et le ou la destinataire parlent la même langue. Si, dans l’exemple ci-dessus, vous apprenez que l’expéditeur·ice parle thaï, vous pouvez traduire la chaîne en thaï et la transférer directement en tant que message, comme ci-dessous :

FB.ui({method: 'apprequests',
  message: 'ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า'
}, requestCallback);

Recommandations

Ajout de données à une invitation

Comme nous l’avons déjà mentionné dans la section Paramètres de la boîte de dialogue, vous pouvez ajouter jusqu’à 255 caractères de données supplémentaires à l’invitation. Ainsi, vous pouvez transférer des informations supplémentaires concernant l’invitation ou ajouter un identifiant qui vous servira à rechercher des informations utiles stockées sur votre serveur.

Prenons l’exemple de Friend Smash!, le projet de jeu démo de Facebook, où les joueur·ses essayent à tour de rôle de « toucher » le plus d’ami·es possible. Lorsqu’un·e joueur·se envoie un défi à un·e autre joueur·se par le biais d’une invitation, le paramètre de données est utilisé pour stocker le dernier score du joueur ou de la joueuse qui a lancé le défi. Le jeu extrait ensuite cette valeur pour le ou la joueur·se qui accepte le défi et en fait le score cible à atteindre pour la partie suivante.

Filtrage des invitations

Lorsque vous créez un sélecteur multi-ami·es personnalisé ou choisissez d’une autre manière les personnes auxquelles vous souhaitez envoyer des invitations, pensez à fournir des filtres pour aider le ou la joueur·se à choisir les destinataires souhaité·es.

Le filtre app_non_users est couramment utilisé lors de l’implémentation d’invitations à l’aide de la boîte de dialogue d’invitation à un jeu. Ce filtre empêche la boîte de dialogue d’invitation à un jeu d’afficher les personnes qui ont déjà joué à votre jeu. Vous pouvez également envisager d’implémenter d’autres filtres, comme les derniers joueurs ou les dernières joueuses avec lesquel·les le ou la joueur·se a interagi ou les joueur·ses de jeux similaires que vous contrôlez. Pour connaître la liste complète des filtres disponibles, consultez le document de référence Boîte de dialogue d’invitation à un jeu : paramètres.

Création de mécanismes attrayants

Créez des mécanismes attrayants pour les joueur·ses lorsqu’ils ou elles rendent visite à leurs ami·es dans le jeu ou interagissent directement avec eux ou elles. Par exemple, si le jeu intègre le concept de voisin·es, accordez des bonus d’énergie lorsque les joueur·ses visitent les environnements de leurs voisin·es. Si la base d’un·e joueur·se est attaquée, autorisez ses ami·es à participer à sa réparation. En règle générale, les joueur·ses aident volontiers leurs ami·es à progresser. Donnez-leur l’occasion de le faire afin d’améliorer l’aspect social de votre jeu et d’attirer davantage de participant·es.

Proposition d’objets intéressants aux joueur·ses

Offrez quelque chose d’utile que le ou la joueur·se pourra utiliser afin d’améliorer la jouabilité ou l’expérience sociale.

Segmentation des joueur·ses et proposition d’invitations pertinentes

Étudiez vos joueur·ses et séparez-les en plusieurs groupes pertinents pour votre jeu (par exemple, les nouveaux joueurs ou les nouvelles joueuses, ceux ou celles qui fabriquent des choses, ceux ou celles qui ont beaucoup d’ami·es, ceux ou celles qui sont impliqué·es, etc.). Pensez aux choses qui leur seront utiles à leur niveau et offrez des choses particulières à chaque groupe de joueur·ses.