Игровые запросы

Игровые запросы позволяют приглашать друзей присоединиться к игре. Игрок может отправлять запросы с призывом к действию одному или нескольким друзьям. Получать запросы могут как участники игры, так и новички.

С помощью игровых запросов можно привлекать новых или повторно вовлекать существующих игроков. Запрос можно отправить в соответствии с одним из двух сценариев:

1. Получатель является другом отправителя и не авторизован в игре. Этот сценарий можно использовать для приглашений.
2. Получатель является другом отправителя и уже авторизован в игре. Этот сценарий можно использовать для отправки уведомлений об очередности хода и просьб о помощи.

Запросы, отправленные во время игры, демонстрируются получателям в разных элементах интерфейса Facebook. Запросы конфиденциальны, поэтому их увидит только получатель. Один запрос можно отправить сразу нескольким получателям, однако адресат видит только информацию об отправителе и не знает, кому ещё был отправлен этот запрос.

Пример игрового запроса в интерфейсе Facebook для ПК.

Запросы можно отправлять из игр на Facebook и с мобильной платформы для iOS и Android. В полной версии Facebook для ПК запросы, если они не отфильтрованы, отображаются в виде всплывающего окна в левом нижнем углу экрана, а также в панели уведомлений. На мобильных платформах запросы, если они не отфильтрованы, появляются в списке уведомлений приложения Facebook. Данные запроса доступны в API Game Request. В целях более качественной интеграции в мобильных играх можно создать пользовательский интерфейс. Запросы следует адаптировать для любых платформ, чтобы они одинаково выглядели на всех устройствах. Однако приглашения, которые отправляет игрок, появятся на всех платформах, которые поддерживают игру.

Запуск диалога запроса

Создать диалог игрового запроса можно с помощью SDK для JavaScript, iOS, Android и Unity. В этих примерах подразумевается, что отправитель авторизован в приложении. Если получатели не указаны, с помощью фильтра вы можете составить список из не более чем 50 друзей. Вы также можете разделить их на зарегистрированных и незарегистрированных. Этот способ поможет повторно вовлечь игроков или стимулировать их приглашать своих друзей.

JavaScript

Отправка запросов с помощью инструмента выбора друзей в диалоге игрового запроса:

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

Когда диалоговое окно закроется, объект response будет содержать результаты отправки, в том числе ID request и массив получателей to. Пример:

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

По умолчанию для отправителя открывается инструмент выбора друзей, где он может выбрать не более 50 получателей.

Отправка запросов конкретному получателю:

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

Если поле to заполнено, отправитель не сможет выбрать других получателей.

Отправка запросов нескольким конкретным получателям:

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

Чтобы указать несколько получателей, введите их ID пользователей через запятую.

Отправка запросов конкретным спискам друзей:

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

Отправка объектов через запросы путем явного указания action_type и 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);
});

Чтобы отправить запрос с уведомлением об очередности хода, не указывайте 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);
});

Также получателей можно разделить на именованные списки, благодаря чему игрок может выбрать из друзей, логически сгруппированных на основании статуса в игре.

Подробнее об этом см. в справочной документации по FB.ui для Facebook SDK для JavaScript.

SDK для iOS

Запуск диалога запроса с помощью инструмента выбора друзей в SDK для 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];

Отправка запросов с явным указанием action_type и object_id для конкретного получателя с помощью 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 для Android

Отправка запроса через инструмент выбора друзей в диалоге запроса с помощью SDK для 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);
}

Отправка запроса с явным указанием действия и объекта с помощью SDK для 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 для Unity

Вот как выполняются запросы в SDK для Unity. Подробнее см. в документации по FB.AppRequest.

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

Параметры диалога

Чтобы точнее настроить поведение диалога игрового запроса, задайте для него дополнительные параметры. Эти параметры описаны ниже.

Данные ответа

Если запрос отправлен через диалог игрового запроса, в обратный вызов будет передан ответ со следующей информацией:

Обработка запросов в игре

Принятие запросов

Когда получатель принимает запрос в полной версии сайта Facebook для компьютеров, он попадает на URL игры, из которой был отправлен запрос. Этот URL содержит дополнительный параметр GET — request_ids. Он представляет собой список разделенных запятой ID запросов, которые принимает пользователь:

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

Принятые получателями запросы не удаляются автоматически. Это должна сделать игра. Чтобы удалить принятый запрос, при запущенной игре посмотрите в API Graph список запросов, отправленных пользователю, и после обработки удалите каждый из них.

Если получатель принимает запрос на мобильной платформе, он переходит в приложение по глубокой ссылке. При загрузке приложения будет учитываться дополнительный параметр — ID запроса. Следить за принятием и удалением запросов на мобильной платформе нужно так же, как и в полной версии. При запуске игры не забывайте регулярно проверять и удалять ожидающие подтверждения запросы.

Чтение запросов

Каждый отправленный запрос имеет уникальный ID объекта запроса. Этот ID представляет объект запроса. Чтобы создать определенный экземпляр запроса, добавьте ID получателя к ID объекта запроса. Этот экземпляр будет содержать все сведения о запросе, который был отправлен конкретному получателю.

Например, при отправке запроса ответ от диалога игрового запроса выглядит следующим образом:

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

Если пытаться найти ID объекта запроса с помощью API Graph, полученный ответ зависит от контекста поиска. Однако ответ всегда представляет полный объект запроса.

Например, если запрос http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN содержит маркер доступа получателя, вы увидите следующий ответ:

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

Обратите внимание, что возвращаются поля to и from. Но если ту же конечную точку вызвать с использованием маркера доступа отправителя или приложения, Facebook выдаст следующий результат:

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

Чтобы с помощью маркера доступа приложения получить полный запрос, который содержит получателя, нужно добавить ID получателя после символа "_". Например, вызов https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} выдает следующие данные:

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

Чтение всех запросов

Чтобы прочитать все запросы, отправленные получателю, создайте запрос для API Graph с указанием USER ACCESS TOKEN получателя, как показано ниже. В результате будет показан список ID запросов для этого пользователя в приложении.

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

Удаление запросов

Принятые получателем игровые запросы не удаляются автоматически. За удаление принятых запросов отвечает разработчик. Вам необходимо удалять принятые запросы за игроков.

Удалить запрос можно одним из следующих способов:

API Graph

Отправьте запрос HTTP DELETE с объединенным параметром 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);
  });
}

Отслеживание запросов для переходов и вознаграждений

Вы можете наградить отправителя игрового запроса, если в результате получатель выполнил определенное действие. Нельзя награждать игроков лишь за отправку запросов, но, например, если после принятия запроса получатель установил игру и достиг определенного уровня, вы можете наградить отправителя.

Чтобы наградить отправителя, нужно узнать, кто он. Это можно сделать двумя способами:

1. При отправке запроса сохраните request_id, возвращенный в ответе из диалога игрового запроса, а затем сопоставьте его, чтобы наградить отправителя.
2. Если человек запустил игру, прочитайте все запросы, связанные с ним. Затем используйте параметр id в поле from, чтобы вознаградить этого пользователя. Если одного игрока пригласили несколько друзей, вы можете наградить первого или всех отправителей.

API Invitable Friends

Локализация

Чтобы играть в вашу игру могли люди со всего мира, Facebook позволяет локализовать requests. Прежде чем переводить запросы, нужно изучить их типы и способы представления. Запросы могут быть стандартными, например "Анна отправила вам запрос", либо содержать просьбу или информацию, например "Анна попросила вас поделиться жизнью" или "Анна отправила вам бомбу". Можно также отправить запрос, чтобы уведомить друга о том, что сейчас его очередь ходить. Все эти примеры доступны для авторизованных в приложении игроков. Если у получателя не установлена игра, он увидит запрос в форме приглашения. Например "Анна пригласила вас поиграть во Friend Smash". Теперь поговорим о том, как перевести эти приглашения.

Перевод приглашений

Facebook автоматически переводит текст в приглашении. Разработчики не контролируют этот процесс. Приглашение переводится на язык получателя.

Приглашение на английском

Приглашение на тайском

В примерах выше обратите внимание, что текст "пригласила поиграть" автоматически переводится на другой язык, в этом случае на тайский. Перевод названия и описания приложения указан в выделенных желтым полях "Отображаемое название" и "Описание" в разделе "Локализация" настроек приложения.

Перевод отображаемого названия и описания

Запросы также могут демонстрироваться в Центре приложений. В Центре приложений отображается "сообщение" запроса. Сообщение может перевести разработчик. На снимках экрана ниже сообщение представлено на английском языке: "Can I have a life to help me through the next level?" (Не поделишься жизнью, чтобы мне удалось добраться до следующего уровня?) и на тайском: "ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า". На данный момент основной текст запроса, "Анна отправила вам запрос", не отображается в Центре приложений.

Запрос в Центре приложений на английском

Запрос в Центре приложений на тайском

Перевод сообщения

Поскольку сообщение передается в виде параметра при вызове диалогового окна с запросом, вы можете сами перевести его, а затем вызвать диалоговое окно и не отправить переведенную строку. Динамически изменить перевод можно перед вызовом диалогового окна. Вы можете сами решить, на какой язык перевести сообщение, потому что этот текст увидит отправитель в предварительном просмотре, а получатель после доставки запроса.

Многие разработчики сначала выясняют язык отправителя, чтобы определить, на какой язык нужно перевести сообщение. Они предполагают, что в большинстве случаев отправитель и получатель говорят на одном языке. В примере выше виден язык отправителя: если это тайский, вы могли бы отправить строку на тайском прямо в сообщении следующим образом:

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

Рекомендации

Добавление данных в запрос

Как уже говорилось в разделе Параметры диалогового окна выше, к запросу можно добавить дополнительные сведения (не более 255 символов). В них вы можете указать более подробную информацию о запросе либо прикрепить к нему идентификатор, который поможет вам найти важную информацию, хранящуюся на сервере.

Например, в игре Facebook Friend Smash игроки по очереди должны постараться "сбить" как можно больше фото друзей. Когда один игрок отправляет другому приглашение посоревноваться, для хранения набранных очков первого игрока используется параметр данных. Игра получает информацию о количестве набранных очков, а игроку, который принял вызов, нужно набрать больше очков.

Фильтруйте приглашения

Если вы создаете пользовательский инструмент выбора друзей или предлагаете игроку другой способ выбрать, кому отправить запросы, предоставьте фильтры. С их помощью игроку будет проще найти получателей.

Чаще всего в приглашениях, реализуемых через диалог игрового запроса, используется фильтр app_non_users. Благодаря этому фильтру в диалоге не появятся люди, которые уже установили игру. Также с помощью фильтров можно найти игроков, которые открывали приложение недавно, или тех, кому нравятся похожие игры. Полный список фильтров см. в разделе Параметры диалогового окна руководства по игровым запросам.

Создайте механизмы вовлечения

Создайте механизмы вовлечения, чтобы игроки могли посещать своих друзей или общаться с ними напрямую. Допустим, если в игре есть соседи, дарите дополнительную энергию игрокам, которые посещают своих соседей. Если на постройку игрока нападают, разрешите друзьям помочь отремонтировать ее. Как правило, игроки любят помогать друзьям развиваться. Если вы предоставите им такую возможность, они с удовольствием будут взаимодействовать друг с другом и, следовательно, чаще играть.

Предложите игроку что-нибудь ценное

Предложите игроку что-нибудь полезное, что поможет добиться лучших результатов в игре или взаимодействовать с друзьями.

Разделите игроков на группы и предлагайте контекстные запросы

Изучите своих игроков и разделите их на группы согласно логике игры (например, можно создать группу новичков, игроков, которые любят строить объекты, игроков со множеством друзей, особо вовлеченных игроков и т. д.). Подумайте, какая помощь была бы полезна им на этом уровне, и предлагайте особые бонусы.