Spieleanfragen

Über Spieleanfragen können Spieler ihre Freunde zu einem Spiel einladen. Anfragen werden von einem Spieler an einen oder mehrere Freunde gesendet und enthalten stets einen Call to Action für das Spiel. Die Empfänger können bereits aktive Spieler oder neue Spieler sein.

Spieleanfragen können dazu verwendet werden, neue Spieler anzusprechen oder vorhandene Spieler zur erneuten Interaktion anzuregen. Anfragen können in zwei Szenarien gesendet werden:

1. Der Empfänger ist ein Freund des Absenders und hat das Spiel noch nicht authentifiziert. Dieses Szenario ist nützlich für Einladungen.
2. Der Empfänger ist ein Freund des Absenders und hat das Spiel bereits authentifiziert. Dieses Szenario ist nützlich für rundenbasierte Benachrichtigungen und Bitten um Hilfe.

Anfragen werden gesendet, während der Absender sich im Spiel befindet, und werden den Empfängern an mehreren Stellen auf Facebook angezeigt. Anfragen sind immer privat und können nur vom Empfänger gesehen werden. Personen können zwar eine Anfrage an mehrere Empfänger gleichzeitig senden, jeder Empfänger sieht aber immer nur die Details des Absenders und nie die anderen Empfänger der Anfrage.

Beispiel einer Spieleanfrage auf Facebook für Desktop.

Spieleanfragen sind für Spiele auf Facebook und für mobile Spiele auf iOS und Android verfügbar. Auf der Facebook-Desktop-Webseite erscheinen Anfragen als Popup mit einem akustischen Signal unten links im Bildschirm sowie im Benachrichtigungssymbol, sofern sie nicht gefiltert werden. Auf mobilen Plattformen werden Anfragen in der Benachrichtigungsliste der Facebook-App angezeigt, sofern sie nicht gefiltert werden. Anfragedaten sind über die Spieleanfrage-API verfügbar. Die Benutzeroberfläche kann angepasst werden, um sie besser in mobile Spiele einzubinden. Deine Implementierung von Anfragen sollte also plattformunabhängig sein und auf allen Plattformen ein konsistentes Nutzererlebnis liefern. Vom Spieler gesendete Einladungen erscheinen aber auf allen von deinem Spiel unterstützten Plattformen.

Starten des Anfrage-Dialogs

Der Spieleanfrage-Dialog wird über das JavaScript-, iOS-, Android- und Unity-SDK generiert. Bei diesen Beispielen wird vorausgesetzt, dass der Absender die App bereits authentifiziert hat. Wenn keine Empfänger angegeben werden, kannst du die Liste der Freunde auf höchstens 50 Freunde begrenzen und sie nach registrierten Spielern oder nicht registrierten Freunden segmentieren. So kannst du jeweils einen eigenen Ablauf für das Anregen zur erneuten Interaktion oder für Einladungen bereitstellen.

JavaScript

Senden von Anfragen über die Mehrfach-Freundesauswahl im Dialog „Spieleanfrage“:

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

Wenn der Dialog geschlossen wird, enthält das response-Objekt die Ergebnisse der Anfrage, einschließlich einer request-ID und eines Arrays aus to-Empfängern. Beispiel:

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

Standardmäßig wird dem Absender eine Mehrfach-Freundesauswahl angezeigt, in der er maximal 50 Empfänger auswählen kann.

Senden von Anfragen an einen bestimmten Empfänger:

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

Wenn das to-Feld angegeben wird, kann der Absender keine weiteren Empfänger auswählen.

Senden von Anfragen an mehrere bestimmte Empfänger:

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

Mehrere Empfänger können über eine durch Komma getrennte Liste von Nutzer-IDs angegeben werden.

Senden von Anfragen an bestimmte Freundeslisten:

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);
}});

Senden von Objekten durch Anfragen, wobei action_type und object_id explizit angegeben werden:

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);
});

Gib bei rundenbasierten Anfragen keine object_id an.

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);
});

Alternativ dazu können Empfänger in benannte Listen aufgeteilt werden, damit der Spieler aus Freunden auswählen kann, die je nach ihrem Status im Spiel logisch gruppiert werden.

Weitere Informationen findest du in der FB.ui-Referenzdokumentation für das Facebook-SDK für JavaScript.

iOS-SDK

Starten des Anfrage-Dialogs über die vom iOS-SDK bereitgestellte Freundesauswahl:

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];

Senden von Anfragen an einen bestimmten Empfänger über den iOS-SDK mit expliziter Angabe von action_type und object_id:

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];

Android-SDK

Senden einer Anfrage über die Freundesauswahl des Anfrage-Dialogs mit dem Android-SDK:

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);
}

Senden einer Anfrage mit expliziter Angabe einer Handlung und eines Objekts über das Android-SDK:

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);
}

Unity-SDK

Hier erfährst du, wie Anfragen im Unity-SDK erfolgen. Weitere Details findest du in der FB.AppRequest-Dokumentation.

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
);

Dialogparameter

Du kannst den Dialog „Spieleanfrage“ mit mehreren zusätzlichen Parametern erstellen, die sein Verhalten festlegen. Diese Parameter werden im Folgenden beschrieben.

Antwortdaten

Wenn eine Anfrage über den Dialog „Spieleanfrage“ versendet wurde, wird eine Antwort mit den folgenden Informationen an den Rückruf übergeben:

Umgang mit Anfragen im Spiel

Annehmen von Anfragen

Wenn ein Empfänger eine Anfrage auf der Facebook-Desktop-Webseite annimmt, wird er zur URL des Spiels geleitet, das die Anfrage gesendet hat. Diese URL enthält den zusätzlichen GET-Parameter request_ids. Dabei handelt es sich um eine durch Komma getrennte Liste mit Anfrage-IDs, die der Nutzer annimmt:

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

Wenn ein Empfänger Anfragen annimmt, werden diese nicht automatisch gelöscht. Dies muss von deinem Spiel übernommen werden. Bei vielen Spielen wird die Liste der ausstehenden Anfragen für einen Nutzer beim Start des Spiels von der Graph API gelesen und jede Anfrage wird nach der Verarbeitung gelöscht.

Wenn ein Empfänger eine Anfrage auf einer mobilen Plattform annimmt, enthält diese einen Deep Link zur App. Beim Laden der App wird ein zusätzlicher Parameter verwendet, nämlich die Anfrage-ID. Auch bei Mobilgeräten gilt dieselbe Aufgabenverteilung zum Annehmen und Löschen von Anfragen. Es bietet sich also an, ausstehende Anfragen beim Start des Spiels zu prüfen und zu löschen.

Lesen von Anfragen

Jede gesendete Anfrage enthält eine eindeutige Anfrageobjekt-ID. Diese ID steht für das Anfrageobjekt. Du kannst diese Anfrageobjekt-ID mit der Nutzer-ID eines Empfängers verketten, um eine spezifische Instanz der Anfrage zu erstellen. Diese steht für eine ganz bestimmte Instanziierung der Anfrage, die an einen speziellen Empfänger gesendet wurde.

Wenn du beispielsweise eine Anfrage sendest, sieht die Antwort des Spieleanfrage-Dialogs wie folgt aus:

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

Wenn du die Anfrageobjekt-ID über die Graph API nachschlägst, erhältst du eine etwas andere Antwort, je nach Anzeigekontext des Lookups. Die Antwort steht aber immer für das komplette Anfrageobjekt.

Wenn du beispielsweise eine Anfrage an http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN mit dem Nutzerzugriffsschlüssel des Empfängers tätigst, erhältst du die folgende Antwort:

{
  "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"
}

Beachte, dass die Felder to und from zurückgegeben werden. Wenn du allerdings denselben Endpunkt mit dem Zugriffsschlüssel des Absenders oder einem App-Zugriffsschlüssel aufrufst, gibt Facebook Folgendes zurück:

{
  "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"
}

Um die vollständige Anfrage inklusive Empfänger über einen App-Zugriffsschlüssel abzurufen, musst du die Nutzer-ID des Empfängers nach einem Unterstrich „_“ anhängen. Ein Aufruf an https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} gibt also beispielsweise Folgendes zurück:

{
  "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"
}

Lesen aller Anfragen

Wenn du alle Anfragen für einen Empfänger lesen möchtest, kannst du den Graph wie weiter unten gezeigt mit dem USER ACCESS TOKEN des Empfängers abfragen. So erhältst du eine Liste der Anfrage-IDs für diesen Nutzer in der App.

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

Löschen von Anfragen

Spieleanfragen werden nach der Annahme durch den Empfänger nicht automatisch gelöscht. Der Entwickler ist dafür zuständig, die Anfrage nach ihrer Annahme zu löschen. Du musst Anfragen nach ihrer Annahme für die Spieler löschen.

Du kannst Anfragen mit folgenden Methoden löschen:

Graph API

Sende eine HTTP-DELETE-Anfrage an die verkettete request_id:

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);
  });
}

Tracking von Anfragen für Weiterempfehlungen und Belohnungen

Du kannst Absender von Spieleanfragen belohnen, wenn der Empfänger aufgrund der Anfrage bestimmte Handlungen ausführt. Du kannst Spieler nicht für das bloße Senden von Anfragen belohnen. Wenn der Empfänger aber beispielsweise nach Annahme der Anfrage das Spiel installiert und ein bestimmtes Level erreicht, kannst du den Absender belohnen.

Um den Absender zu belohnen, musst du wissen, wer er ist. Es gibt zwei Möglichkeiten, dies herauszufinden:

1. Speichere beim Senden der Anfrage die in der Antwort vom Dialog „Spieleanfrage“ zurückgegebene request_id und gleiche sie beim Empfang ab, um den Absender zu belohnen.
2. Lies alle Anfragen für einen Spieler, wenn er das Spiel startet, und belohne den Absender basierend auf der id im from-Feld seiner Anfragen. Wenn ein Spieler von mehreren Freunden eingeladen wurde, kannst du entweder den ersten oder alle Absender belohnen.

Invitable Friends API

Lokalisierung

Damit du einer globalen Zielgruppe das optimale Nutzererlebnis bereitstellen kannst, unterstützt Facebook die Lokalisierung von requests. Bevor du Anfragen übersetzt, musst du die verschiedenen Arten von Anfragen kennen und wissen, wie diese angezeigt werden. Anfragen können als der Standardtext „Anita hat dir eine Anfrage gesendet“ angezeigt werden. Bei Angabe eines Aktion/Objekt-Paares kann auch z. B. „Anita hat dich um ein Leben gebeten“ oder „Anita hat dir eine Bombe gesendet“ angezeigt werden. Es gibt auch eine Rundenanfrage, um Personen darauf hinzuweisen, dass sie in einem Spiel gegen ihren Freund an der Reihe sind. All diese Beispiele werden für Spieler angezeigt, die das Spiel autorisiert haben. Wenn der Empfänger das Spiel nicht installiert hat, sieht er die Anfrage in Form einer Einladung. Beispiel: „Anita hat dich eingeladen, Friend Smash! zu spielen!“ Sehen wir uns an, wie diese Beispiele übersetzt werden.

Übersetzen von Einladungen

Der Text von Einladungen wird automatisch von Facebook übersetzt und kann nicht von Entwicklern festgelegt werden. Er wird in die Sprache des Empfängers übersetzt.

Einladungsbenachrichtigung auf Englisch

Einladungsbenachrichtigung auf Thai

Beachte, dass der Text „hat dich eingeladen, zu spielen“ in den obigen Beispielen automatisch in die andere Sprache übersetzt wurde (in diesem Fall Thai). Der Name und die Beschreibung der App werden im Abschnitt „Lokalisieren“ der App-Einstellungen unter „Anzeigename“ und „Beschreibung“ in den gelben Feldern unten übersetzt.

Übersetzen des Anzeigenamens und der Beschreibung der App

Anfragen können auch im App Center angezeigt werden. Im App Center wird die „Nachricht“ der Anfrage angezeigt. Die Nachricht kann vom Entwickler übersetzt werden. In den folgenden Beispielen lautet die Nachricht „Can I have a life to help me through the next level?“ auf Englisch und „ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า“ auf Thai. Der Haupttext für die Anfrage, „Anita hat dir eine Anfrage gesendet“, wird derzeit nicht im App Center angezeigt.

Anfrage im App Center auf Englisch

Anfrage im App Center auf Thai

Übersetzen der Nachricht

Da die Nachricht beim Aufruf des Anfrage-Dialogs als Parameter übergeben wird, kannst du sie selber übersetzen, bevor du den Anfrage-Dialog aufrufst, und den übersetzten String als Nachricht übergeben. Wenn du die Übersetzung dynamisch ändern möchtest, solltest du dies vor dem Aufruf des Dialogs tun. Du kannst entscheiden, welche Sprache angezeigt werden soll, da es sich hierbei um den Text handelt, den der Absender in der Anfragevorschau und der Empfänger beim Empfang der Anfrage sieht.

Viele Entwickler erkennen die Ländereinstellung des Absenders und bestimmen anhand dieser, welche Sprache für die Nachricht verwendet werden soll. Sie gehen davon aus, dass der Absender und der Empfänger meistens dieselbe Sprache sprechen. Im oben gezeigten Beispiel könntest du die Ländereinstellung des Absenders prüfen. Wenn die Ländereinstellung beispielsweise Thai ist, kannst du den String wie folgt direkt als Nachricht auf Thai senden:

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

Best Practices

Anhängen von Daten an eine Anfrage

Wie im Abschnitt Dialogparameter weiter oben erwähnt, kannst du zusätzliche Daten im Umfang von bis zu 255 Zeichen an eine Anfrage anhängen. Dadurch kannst du entweder zusätzliche Informationen zur Anfrage übertragen oder eine ID anhängen, anhand welcher du später relevante Informationen abrufen kannst, die auf deinem Server gespeichert sind.

Im Facebook-Beispiel-Spielprojekt Friend Smash beispielsweise sind die Spieler nacheinander an der Reihe und versuchen, so viele Freunde wie möglich zu „smashen“. Wenn ein Spieler per Anfrage eine Herausforderung an einen anderen Spieler sendet, speichert der data-Parameter die letzte Punktzahl des Herausforderers. Das Spiel extrahiert diesen Wert dann für den Empfänger und speichert ihn als Ziel-Punktzahl für das nächste Spiel.

Filtern von Einladungen

Wenn du deine eigene Mehrfach-Freundesauswahl entwickelst oder anderweitig eine Auswahl bietest, an wen ein Spieler Anfragen senden kann, kannst du Filter anbieten, damit der Spieler die gewünschten Empfänger einfacher auswählen kann.

Bei der Implementierung von Einladungen mit dem Dialog „Spieleanfrage“ wird häufig der app_non_users-Filter verwendet. Dieser Filter verhindert, dass Personen, die dein Spiel bereits gespielt haben, im Dialog „Spieleanfrage“ angezeigt werden. Andere potenziell nützliche Filter sind Spieler, mit denen zuletzt interagiert wurde, oder Spieler von ähnlichen Spielen, die dir gehören. Eine vollständige Liste der verfügbaren Filter findest du in der Referenzdokumentation zu Parametern für den Dialog „Spieleanfrage“.

Erstelle ansprechende Abläufe

Erstelle ansprechende Abläufe für Spieler, die ihre Freunde im Spiel besuchen oder direkt mit diesen interagieren. Wenn Spieler in deinem Spiel beispielsweise Nachbarn haben können, gib ihnen Bonusenergie, wenn sie die Umgebungen ihrer Nachbarn besuchen. Wenn die Basis eines Spielers angegriffen wird, ermögliche es seinen Freunden, bei der Reparatur zu helfen. Spieler schätzen es generell, ihre Freunde im Spiel zu unterstützen. Gib ihnen daher Chancen, dies zu tun, um ein besseres soziales Erlebnis zu erreichen und mehr Personen zum Spielen anzuregen.

Mache Gegenstände wertvoll für den Spieler

Biete etwas an, das wertvoll für den Spieler ist und mit dem er das Spiel- oder das soziale Erlebnis verbessern kann.

Segmentiere Spieler und biete kontextbezogene Anfragen an

Evaluiere deine Spieler und teile sie in verschiedene Gruppen ein, die für dein Spiel sinnvoll sind (z. B. neue Spieler, Spieler, die Gegenstände im Spiel herstellen, Spieler mit vielen Freunden, engagierte Spieler usw.). Überlege, welche Gegenstände im jeweiligen Level nützlich für die Spieler wären, und biete spezielle Elemente für jede Gruppe an.