Solicitudes de juegos

Las solicitudes de juegos proporcionan a los jugadores una vía para invitar a amigos a jugar. Se pueden enviar a uno o más amigos y siempre incluyen una llamada a la acción relacionada con el juego. Los destinatarios pueden ser personas que ya juegan o nuevos jugadores.

Las solicitudes de juegos pueden utilizarse para atraer a nuevos jugadores o para volver a interactuar con personas que ya han jugado. Pueden enviarse solicitudes en dos situaciones:

1. El destinatario es amigo del remitente y no ha autenticado el juego. Esta situación resulta útil en el caso de las invitaciones.
2. El destinatario es amigo del remitente y ha autenticado el juego anteriormente. Esta situación resulta útil en el caso de las notificaciones por turnos y las peticiones de ayuda.

Las solicitudes se envían mientras el remitente está en el juego y se muestran a los destinatarios en varios lugares de Facebook. Son siempre privadas y solo las puede ver el destinatario. Aunque es posible enviar una única solicitud a varios destinatarios a la vez, el destinatario de una solicitud solamente verá los datos del remitente, nunca los del resto de los destinatarios.

Ejemplo de solicitud de juego mostrada en Facebook para ordenadores.

Las solicitudes de juegos están disponibles para Juegos en Facebook y juegos para móviles en iOS y Android. En el sitio web de Facebook para ordenadores, si las notificaciones no se han filtrado, las solicitudes se indican en forma de elemento emergente sonoro en la parte inferior izquierda de la pantalla y en el icono de notificaciones. En plataformas para móviles, si las notificaciones no se han filtrado, se mostrarán en la lista de notificaciones de la aplicación de Facebook. Los datos de solicitudes están disponibles mediante la API de solicitudes de juegos y se pueden crear interfaces de usuario personalizadas para reforzar la integración en juegos para móviles. Por lo tanto, la implementación de las solicitudes debe ser válida para todas las plataformas y proporcionar una experiencia de usuario coherente en todos los dispositivos, independientemente de la plataforma que se utilice. No obstante, las invitaciones que envíe el jugador aparecerán en la combinación de plataformas que admita tu juego.

Iniciar el cuadro de diálogo de la solicitud

El cuadro de diálogo de la solicitud de juego se genera mediante los SDK para JavaScript, iOS, Android y Unity. Estos ejemplos presuponen que el remitente ya ha autenticado la aplicación. Si no se especifica ningún destinatario, puedes filtrar la lista de amigos para limitarla a 50 o menos; también puedes segmentarla por jugadores registrados o amigos sin registrar. Esta opción resulta útil para proporcionar un proceso independiente con el que volver a interactuar con jugadores o invitar a nuevos usuarios.

JavaScript

Envío de solicitudes mediante el selector de amigos que proporciona el cuadro de diálogo de la 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 forma predeterminada, se muestra al remitente un selector de amigos que le permite seleccionar un máximo de 50 destinatarios.

Envío de 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 el campo to, el remitente no podrá seleccionar a más destinatarios.

Envío de 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);
});

Se pueden especificar varios destinatarios por medio de una lista separada por comas con los identificadores de usuario.

Envío de solicitudes a listas específicas de amigos:

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

Envío de objetos mediante solicitudes indicando de forma expresa los campos 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 el campo 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);
});

Los destinatarios también pueden dividirse en listas con nombre, que permiten al jugador elegir entre amigos agrupados de forma lógica en función de su estado en el juego.

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

iOS SDK

Inicio del cuadro de diálogo de la solicitud mediante el selector de amigos que proporciona el iOS SDK:

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

Envío de solicitudes indicando de forma expresa los campos action_type y object_id para un destinatario específico mediante el iOS SDK:

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

Envío de 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);
}

Envío de una solicitud indicando de forma expresa 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);
}

Unity SDK

A continuación se describe cómo realizar solicitudes en el Unity SDK. Consulta la documentación sobre 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 la solicitud de juego puede crearse con una serie de parámetros adicionales que determinan su comportamiento. Estos parámetros se describen a continuación.

Datos de respuesta

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

Gestionar solicitudes en el juego

Aceptar solicitudes

Cuando un destinatario acepta una solicitud en el sitio web de Facebook para ordenadores, se le envía a la URL del juego que ha enviado la solicitud. Esta URL contiene un parámetro adicional, request_ids, para la solicitud GET. Este parámetro consiste en una lista delimitada por comas de los identificadores de la solicitud que acepta el usuario:

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

Las solicitudes no se eliminan automáticamente cuando las acepta un destinatario. Debe eliminarlas tu juego. Un práctica habitual es, al iniciarse un juego, leer en la API Graph la lista de solicitudes pendientes del usuario y eliminar cada una de ellas tras procesarlas.

Cuando un destinatario acepta una solicitud en una plataforma para móviles, se crea un enlace profundo a la aplicación. Al cargarse la aplicación, estará presente otro parámetro: el identificador de la solicitud. La responsabilidad de aceptar y borrar solicitudes también se aplica a los dispositivos móviles. Se recomienda comprobar y borrar las solicitudes pendientes cuando se inicia el juego.

Leer solicitudes

Cada solicitud enviada tiene un identificador de objeto de solicitud único. Este identificador representa el objeto de solicitud. El identificador de objeto de solicitud puede concatenarse con un identificador de usuario de destinatario para crear una instancia específica de la solicitud. Representa una instancia de la solicitud que se ha enviado a un destinatario concreto.

Por ejemplo, al enviar una solicitud, la respuesta del cuadro de diálogo de la solicitud de juego será parecida a la siguiente:

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

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

Por ejemplo, si se realiza una consulta a http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN con el identificador de acceso de usuario del destinatario, se mostrará 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"
}

Observa que se devuelven los campos to y from. Sin embargo, si se llama al mismo extremo utilizando el identificador de acceso del remitente o el identificador de acceso a la aplicación, 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 una solicitud completa que incluya al destinatario utilizando un identificador de acceso a la aplicación, tendrás que añadir el identificador de usuario del destinatario tras un carácter de guion bajo (“_”). Así, 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 dirigidas a un destinatario, puedes consultar el gráfico utilizando el parámetro USER ACCESS TOKEN del destinatario, tal y como se muestra a continuación. Esta consulta devolverá una lista de identificadores de solicitud para dicho usuario en la aplicación.

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

Eliminar solicitudes

Las solicitudes de juegos no se eliminan automáticamente cuando el destinatario las acepta. Esta acción es responsabilidad del desarrollador. Debes eliminar las solicitudes en nombre de los jugadores una vez que se hayan aceptado.

Para ello, puedes utilizar uno de los siguientes métodos:

API Graph

Envía una solicitud HTTP DELETE al parámetro 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 a efectos de referencia y recompensa

Puedes recompensar a los remitentes de solicitudes de juegos en función de si los destinatarios realizan determinadas acciones como resultado. Por ejemplo, no puedes recompensar a los jugadores simplemente por enviar solicitudes; sin embargo, si el destinatario descarga el juego y alcanza un nivel determinado como resultado de aceptar la solicitud, puedes recompensar al remitente.

Para recompensar al remitente, primero tienes que saber quién es. Puedes averiguarlo de dos formas:

1. Al enviar la solicitud, almacena el valor de request_id devuelto en la respuesta del cuadro de diálogo de la solicitud de juego y cotéjalo al recibirlo para recompensar al remitente.
2. Lee todas las solicitudes de un jugador cuando haya iniciado el juego y recompensa al remitente a partir del parámetro id del campo from de sus solicitudes. Si varios amigos han invitado a un jugador, puedes optar por recompensar al primero de todos los remitentes.

API de invitación de amigos

Localización

Con el fin de ayudarte a proporcionar la mejor experiencia de usuario posible a tu audiencia global, Facebook permite localizar objetos requests. Antes de traducir las solicitudes, es importante conocer los diferentes tipos que existen y cómo se muestran. Las solicitudes pueden verse como el estándar “Anita te ha enviado una solicitud” o, si se especifica un par acción-objeto, como “Anita te ha pedido una vida” o “Anita te ha enviado una bomba”. Existe también una solicitud de turno que avisa a la persona cuando le toca jugar en una partida contra un amigo. Todos estos ejemplos se muestran a los jugadores que han autenticado el juego. Si el destinatario no ha descargado el juego, verá la solicitud en forma de invitación. Por ejemplo, “Anita te ha invitado a jugar a Friend Smash”. Veamos cómo traducir las invitaciones.

Traducir invitaciones

Facebook traduce automáticamente el texto de las invitaciones, por lo que los desarrolladores no tienen ningún control sobre este aspecto. El texto 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, puede observarse que el texto “invited you to play” se traduce automáticamente a otro idioma, en este caso, al tailandés. El nombre y la descripción de la aplicación se traducen en la sección “Localización” de la configuración de las aplicaciones, “Nombre para mostrar” y “Descripción” respectivamente, en los cuadros amarillos que se muestran a continuación.

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

Las solicitudes también pueden mostrarse en el Centro de aplicaciones. En el Centro de aplicaciones, se muestra el “mensaje” de la solicitud. El desarrollador puede traducir este mensaje. En los ejemplos siguientes, el mensaje es “Can I have a life to help me through the next level?” en inglés y “ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า” en tailandés. En estos momentos, el texto principal de la solicitud (“Anita sent you a request”) no se muestra en el Centro de aplicaciones.

Solicitud en inglés en el Centro de aplicaciones

Solicitud en tailandés en el Centro de aplicaciones

Traducir el mensaje

Dado que el mensaje se pasa en forma de parámetro cuando se invoca el cuadro de diálogo de la solicitud, puedes traducirlo tú mismo antes de invocar el cuadro de diálogo y pasar la cadena traducida en forma de mensaje. Si quieres cambiar la traducción de forma dinámica, hazlo antes de invocar el cuadro de diálogo. Tú decides en qué idioma quieres que se muestre, ya que verán el mismo texto el remitente en la vista previa de la solicitud y el destinatario al recibirla.

Muchos desarrolladores detectan la configuración regional del remitente para determinar el idioma que debe utilizar el mensaje. Dan por sentado que, en la mayoría de las ocasiones, el remitente y el destinatario hablan el mismo idioma. En el ejemplo anterior, podrías buscar la configuración regional del remitente (es decir, tailandés) y enviar la cadena como un mensaje en el idioma correspondiente, del siguiente modo:

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

Prácticas recomendadas

Añade datos a una solicitud

Tal y como se menciona en la sección Parámetros del cuadro de diálogo anterior, puedes añadir hasta 255 caracteres de datos adicionales para enviarlos con la solicitud. Puedes utilizar esta opción para transferir información adicional relacionada con la solicitud o para añadir un identificador que puedes utilizar más adelante con el fin de buscar información pertinente almacenada en tu servidor.

A modo de ejemplo, en el proyecto de juego de muestra de Facebook Friend Smash, los jugadores se turnan para destruir al mayor número posible de amigos. Cuando un jugador envía un desafío a otro mediante una solicitud, se utiliza el parámetro de datos para almacenar la última puntuación del jugador que lanza el desafío. A continuación, el juego extrae este valor para el destinatario del desafío y lo convierte en la puntuación objetivo de la siguiente partida.

Filtra las invitaciones

Al crear un selector de amigos personalizado o elegir a quién enviar solicitudes, considera la posibilidad de ofrecer filtros para ayudar al jugador a elegir a los destinatarios.

El filtro app_non_users suele utilizarse al implementar invitaciones mediante el cuadro de diálogo de la solicitud de juego. Este filtro evita que el cuadro de diálogo muestre a personas que ya hayan jugado anteriormente al juego. Otros filtros que te puede interesar aplicar son los de jugadores con los que se haya interactuado hace poco o los de usuarios de juegos similares que controlas. Puedes consultar la lista completa de filtros disponibles en el documento de referencia sobre los parámetros del cuadro de diálogo de la solicitud de juego.

Crea mecanismos de interacción

Crea mecanismos que permitan a los jugadores visitar a sus amigos en el juego o interactuar directamente con ellos. Por ejemplo, si el juego admite el concepto de vecinos, concede energía extra cuando los jugadores visiten el entorno de sus vecinos. Si están atacando la base de un jugador, deja que sus amigos le ayuden a repararla. A los jugadores les suele gustar ayudar a sus amigos a progresar; darles la oportunidad de hacerlo mejora la experiencia social y aumenta el número de jugadores.

Crea objetos valiosos para los jugadores

Ofrece a los jugadores cosas que les resulten valiosas y que puedan utilizar para mejorar su experiencia social o de juego.

Segmenta a los jugadores y ofrece solicitudes con contexto

Estudia a tus jugadores y distribúyelos en grupos que guarden coherencia con tu juego (por ejemplo, nuevos jugadores, aquellos a los que les gusta construir, usuarios con muchos amigos, los más activos, etcétera). Piensa qué tipo de cosas les resultarían útiles en su nivel y ofrece objetos específicos a cada segmento.