Solicitudes de juegos

Las solicitudes de juegos ofrecen a los jugadores un mecanismo para invitar a sus amigos a jugar. Un jugador envía solicitudes a uno o más amigos, que siempre incluyen una llamada a la acción para el juego. Los destinatarios pueden ser jugadores preexistentes o nuevos.

Las solicitudes de juegos se pueden usar para atraer a jugadores nuevos o para volver a interactuar con jugadores actuales. Se pueden enviar solicitudes en dos situaciones:

1. El destinatario es amigo del remitente y todavía no autenticó el juego. En esta situación conviene usar las invitaciones.
2. El destinatario es amigo del remitente y ya autenticó el juego. En esta situación, conviene usar notificaciones por turnos y peticiones de ayuda.

Las solicitudes se envían mientras el remitente usa el juego y se muestran a los destinatarios en diferentes ubicaciones de Facebook. Las solicitudes siempre son privadas y solo los destinatarios pueden verlas. Mientras que una solicitud individual se puede enviar a varios destinatarios a la vez, la persona que recibe la solicitud solo verá los detalles del remitente. Nunca verá a los demás destinatarios de la solicitud.

Ejemplo de una solicitud de juego que se muestra en Facebook para computadoras.

Las solicitudes de juegos están disponibles para juegos en Facebook y juegos para celulares con iOS y Android. En el sitio de Facebook para computadoras, las solicitudes aparecen como una notificación emergente con sonido en la parte inferior izquierda de la pantalla, así como en el icono de notificaciones, siempre que no se filtren. En las plataformas para celulares, las solicitudes aparecen en la lista de notificaciones de la app de Facebook, siempre que no se filtren. Los datos de la solicitud están disponibles a través de la API de solicitudes de juegos. También se pueden crear UI personalizadas para lograr una experiencia más integrada en los juegos para celulares. Por lo tanto, tu implementación de solicitudes debe ser independiente de cualquier plataforma y proporcionar una experiencia de usuario coherente en todas. Sin embargo, las invitaciones enviadas por el jugador aparecerán en todas las combinaciones de plataformas que sean compatibles con tu juego.

Lanzar el cuadro de diálogo de solicitud

El cuadro de diálogo de solicitud de juego se genera mediante el SDK para JavaScript, iOS, Android y Unity. Estos ejemplos suponen que el remitente ya autenticó la app. Si no se especifican destinatarios, puedes filtrar la lista de amigos hasta un límite de 50 o menos, y puedes segmentar por jugadores registrados o amigos no registrados. Esto te resultará útil si deseas proporcionar procesos independientes para las invitaciones o las interacciones para recuperar jugadores.

JavaScript

Enviar solicitudes mediante el selector de amigos que proporciona el cuadro de diálogo de solicitud de juego:

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

Cuando se cierre el cuadro de diálogo, el objeto response contendrá los resultados del envío, incluido un identificador request y una matriz de destinatarios to. Por ejemplo:

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

De manera predeterminada, el remitente verá un selector de amigos que le permitirá seleccionar hasta un máximo de 50 destinatarios.

Enviar solicitudes a un destinatario específico:

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

Si se especifica un valor en el campo to, el remitente no podrá seleccionar destinatarios adicionales.

Enviar solicitudes a varios destinatarios específicos:

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

Puedes especificar varios destinatarios utilizando una lista separada por comas que contenga los identificadores de usuarios.

Enviar solicitudes a listas de amigos específicas:

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

Enviar objetos mediante solicitudes, en las que se declare explícitamente un action_type y 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);
});

En el caso de las solicitudes por turnos, no especifiques object_id:

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

Como alternativa, es posible dividir los destinatarios en listas con nombres asignados, lo que permite al jugador elegir entre amigos agrupados de manera lógica según el estado en el juego.

Para obtener más información, consulta la documentación de referencia de FB.ui correspondiente al SDK de Facebook para JavaScript.

SDK para iOS

Activar el cuadro de diálogo de solicitud con el selector de amigos que proporciona el SDK para 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];

Enviar solicitudes en las que se declare explícitamente un action_type y un object_id para un destinatario específico mediante el SDK para 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];

Android SDK

Enviar una solicitud utilizando el selector de amigos del cuadro de diálogo de solicitud mediante el 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);
}

Enviar una solicitud en la que se declare explícitamente una acción y un objeto mediante el 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);
}

SDK para Unity

Esta es la manera de hacer solicitudes en el SDK para Unity. Consulta la documentación de FB.AppRequest para obtener más información.

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

Parámetros del cuadro de diálogo

El cuadro de diálogo de solicitud de juego se puede crear con un número de parámetros adicionales que determine su comportamiento. Estos parámetros se describen a continuación.

Datos de la respuesta

Cuando se envía una solicitud mediante el cuadro de diálogo de solicitud de juego, se pasará una respuesta a la devolución de llamada con la siguiente información:

Administrar solicitudes dentro del juego

Aceptar solicitudes

Cuando un destinatario acepta una solicitud en el sitio de Facebook para computadoras, se lo dirige a la URL del juego que envió la solicitud. La URL contendrá una solicitud adicional GET del parámetro request_ids, que es una lista de valores separados por comas de los identificadores de la solicitud que el usuario está aceptando:

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

Las solicitudes no se eliminan de forma automática cuando un destinatario las acepta. Es responsabilidad de tu juego eliminarlas. Una manera común de hacer esto sería que el juego se inicie, lea en la API Graph la lista de solicitudes pendientes para ese usuario y elimine cada una después de procesarla.

Cuando un destinatario acepta una solicitud en una plataforma para celulares, se establece un enlace profundo con la app. Durante la carga de la app habrá un parámetro adicional, el identificador de la solicitud. La misma responsabilidad en cuanto a la aceptación y eliminación de solicitudes se aplica también a las plataformas para celulares. Se recomienda comprobar y eliminar las solicitudes pendientes durante el inicio del juego.

Leer solicitudes

Cada solicitud tiene un identificador de objeto de solicitud único que representa el objeto de la solicitud. Este identificador representa el objeto de la solicitud. El identificador de objeto de la solicitud se puede concatenar con un identificador de usuario del destinatario para crear una instancia específica de la solicitud. Esto representa una creación de instancias de la solicitud, que se envió a un destinatario específico.

Por ejemplo, cuando se envíe una solicitud, la respuesta del cuadro de diálogo de solicitud de juego tendrá un aspecto similar al siguiente:

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

Si buscas el identificador del objeto de solicitud mediante la API Graph, la respuesta que recibirás será ligeramente diferente, según el contexto de visualización de la búsqueda, pero la respuesta siempre representará al objeto de respuesta completo.

Por ejemplo, si se realiza una consulta a http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN con el token de acceso de usuario del destinatario, verás la siguiente respuesta:

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

Ten en cuenta que se devuelven los campos to y from. Sin embargo, si se llama al mismo punto de conexión usando el token de acceso del remitente, o un token de acceso a la app, Facebook devolverá lo siguiente:

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

Para obtener la respuesta completa que incluye el destinatario mediante un token de acceso a la app, deberás anexar el identificador de usuario del destinatario después de un guion bajo (_). Entonces, por ejemplo, una llamada a https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} devuelve:

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

Leer todas las solicitudes

Para leer todas las solicitudes hechas a un destinatario, puedes consultar la gráfica como se muestra a continuación, usando USER ACCESS TOKEN del destinatario. Se devolverá una lista de los identificadores de solicitudes correspondientes a ese usuario en la app.

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

Eliminar solicitudes

Las solicitudes de juego no se eliminan automáticamente después de que el destinatario las acepta. El desarrollador es responsable de eliminar la solicitud después de que se aceptó. Debes eliminar las solicitudes en nombre de los jugadores una vez que las aceptaron.

Puedes eliminar una solicitud mediante los siguientes métodos:

API Graph

Envía una solicitud HTTP DELETE al identificador request_id concatenado:

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

Realizar un seguimiento de las solicitudes para referencias y recompensas

Puedes recompensar al remitente de la solicitud de juego en función de acciones determinadas que el destinatario realice como resultado. Por ejemplo, no puedes recompensar a jugadores solamente por enviar solicitudes, pero si el destinatario instala el juego y alcanza un nivel determinado como resultado de que aceptó la solicitud, puedes recompensar al remitente.

Para recompensar al remitente, necesitarás saber a quién recompensar. Hay dos maneras de conseguirlo:

1. Cuando envíes la solicitud, guarda el identificador request_id devuelto en la respuesta del cuadro de diálogo de solicitud de juego y relaciónalo en el momento de recibirlo para recompensar al remitente.
2. Lee todas las solicitudes hechas a un jugador cuando inició el juego y recompensa al remitente según el id del campo from de sus solicitudes. Si varios amigos invitaron a un jugador, puedes elegir recompensar al primero o a todos los remitentes.

API de invitación de amigos

Localización

Con el fin de ayudarte a ofrecer la mejor experiencia de usuario para tu público a nivel mundial, Facebook admite la localización de requests. Antes de traducir las solicitudes, es importante que conozcas los diferentes tipos de solicitudes y la manera en que se muestran. Las solicitudes se pueden ver en la forma estándar "Anita te envió una solicitud" o, si se especifica un par de objetos de acción, "Anita te pidió una vida" o "Anita te envió una bomba". También existe una solicitud de turno, que avisa a las personas cuando es su turno en un juego contra un amigo. Los jugadores que autorizaron el juego ven todos esos ejemplos. Si el destinatario no tiene el juego instalado, verá la solicitud en forma de una invitación. Por ejemplo, "Anita te invitó a jugar Friend Smash". Veamos cómo traducir cada una de estas solicitudes.

Traducir invitaciones

Facebook traduce automáticamente el texto de las invitaciones y los desarrolladores no tienen control sobre este proceso. Se traduce al idioma del destinatario.

Notificación de invitación en inglés

Notificación de invitación en tailandés

En los ejemplos anteriores, puedes observar que el texto "te invitó a jugar" se traduce automáticamente al otro idioma, en este caso, al tailandés. El nombre de la app y su descripción se traducen en la sección "Localización" de la configuración de la app, en "Nombre para mostrar" y "Descripción" en los cuadros amarillos que se muestran a continuación.

Traducción del nombre para mostrar y la descripción de la app

Las solicitudes también pueden aparecer en el centro de apps. En el centro de apps, se muestra el "mensaje" de la solicitud. El desarrollador puede traducir el mensaje. En los ejemplos siguientes, el mensaje es "Can I have a life to help me through the next level?" (¿Me das una vida que me ayude a pasar al siguiente nivel?) en inglés y "ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า" en tailandés. Actualmente, el texto principal de la solicitud "Anita te envió una solicitud" no se muestra en el centro de apps.

Solicitud en el centro de apps en inglés

Solicitud en el centro de apps en tailandés

Traducir el mensaje

Como el mensaje se incluye en forma de parámetro al invocarse el cuadro de diálogo de solicitud, puedes traducirlo por tu cuenta antes de invocar el cuadro de diálogo de solicitud e incluir la cadena traducida como el mensaje. Si quieres cambiar la traducción de manera dinámica, hazlo antes de invocar el cuadro de diálogo. Tú decides en qué idioma quieres mostrarlo, pues este será el mismo texto que el remitente verá en la vista previa de la solicitud y que el destinatario verá al recibir la solicitud.

Muchos desarrolladores detectan la configuración regional del remitente y usan esa información para determinar el idioma para usar en el mensaje. Asumen que, en la mayoría de los casos, el remitente y el destinatario hablan el mismo idioma. En el ejemplo anterior, es posible observar la configuración regional del remitente y, si es tailandés, podrías enviar la cadena en tailandés directamente como el mensaje, así:

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

Prácticas recomendadas

Anexo de datos a una solicitud

Como se menciona en la sección Parámetros del cuadro de diálogo, puedes anexar hasta 255 caracteres de datos adicionales para enviarlos junto con la solicitud. Puedes usar esta característica para transferir información adicional relacionada con la solicitud o agregar un identificador que después puedas usar para buscar información relevante almacenada en tu servidor.

Por ejemplo, en el proyecto de juego de ejemplo de Facebook, Friend Smash, los jugadores se turnan en la competencia para "destrozar" la mayor cantidad de amigos posible. Cuando un jugador envía un desafío a otro mediante una solicitud, el parámetro "data" se usa para almacenar la última puntuación del retador. A continuación, el juego extrae este valor para el jugador que recibe el desafío y lo convierte en la puntuación objetivo para el siguiente juego.

Filtrar las invitaciones

Cuando crees un selector de amigos personalizado, o algún otro mecanismo para elegir a quién se enviarán las invitaciones, considera ofrecer filtros que ayuden al jugador a elegir a los destinatarios deseados.

Un filtro que se suele usar al implementar las invitaciones con el cuadro de diálogo de solicitud de juego es app_non_users. Este filtro evita que el cuadro de diálogo de solicitud de juego muestre personas que ya jugaron antes con tu juego. También podrías considerar usar filtros de jugadores que interactuaron recientemente o de jugadores de juegos similares que tú controlas. Encontrarás la lista completa de los filtros disponibles en el documento de referencia "Parámetros del cuadro de diálogo de solicitud de juego".

Crear mecanismos atractivos

Crea mecanismos atractivos para los jugadores cuando visiten a sus amigos en el juego o interactúen directamente con ellos. Por ejemplo, si el juego admite el concepto de vecinos, concede energía adicional cuando los jugadores visiten los entornos de sus vecinos. Si la base de un jugador es objeto de un ataque, permite que sus amigos le ayuden a repararla. Generalmente, los jugadores valoran ayudar a sus amigos a avanzar, de modo que darles oportunidades para hacerlo se traduce en una experiencia social más agradable y en una cantidad mayor de jugadores activos.

Convertir el objeto en algo valioso para el jugador

Ofrece algo que el jugador considere valioso y que pueda usar para mejorar su partida o su experiencia social.

Segmentar a los jugadores y ofrecer solicitudes en contexto

Evalúa a tus jugadores y agrúpalos como mejor le convenga a tu juego (por ejemplo, por jugadores nuevos, jugadores que están creando algo, jugadores con muchos amigos, jugadores activos, etc.). Piensa en lo que podría resultarles útiles en el nivel en el que se encuentran y ofrece cosas específicas a cada segmento.