Маркеры доступа для платформ Meta

Маркер доступа — это строка с непрозрачной структурой, которая идентифицирует пользователя, приложение или Страницу и может использоваться приложением для вызовов Graph API. В маркере содержится информация о том, до какого срока он действителен и каким приложением сгенерирован. Чтобы пройти проверки конфиденциальности, большинство вызовов API в приложениях Meta должны содержать маркер доступа. Для разных сценариев использования предусмотрены разные маркеры доступа и способы их получения.

Маркеры доступа пользователя

На различных платформах для генерации маркеров доступа пользователей используются разные API, но в основе процесса лежит общая для всех платформ схема:

Краткосрочные и долгосрочные маркеры

Маркеры доступа пользователей бывают двух видов: краткосрочные и долгосрочные. Краткосрочные маркеры обычно действуют примерно 1–2 часа, а долгосрочные — около 60 дней. Стоит учитывать, что срок действия маркера доступа может измениться без предупреждения или закончиться раньше. Подробные сведения см. в разделе, посвященном обработке ошибок.

При входе на веб-платформу создаются только краткосрочные маркеры, но их можно преобразовать в долгосрочные. Для этого нужно отправить с сервера вызов API с секретом приложения.

Мобильные приложения, использующие Facebook SDK для iOS и Android, по умолчанию получают долгосрочные маркеры.

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

Переносимость маркеров

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

Переносить маркеры между клиентом и сервером следует через защищенное HTTPS-соединение, чтобы обеспечить безопасность аккаунтов. Информацию о последствиях перемещения маркеров между клиентами и сервером см. здесь.

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

Android

Facebook SDK для Android автоматически управляет маркерами доступа пользователей с помощью класса com.facebook.AccessToken. Чтобы узнать больше о получении маркера доступа пользователя, интегрируйте вход через Facebook для Android. Чтобы получить маркер доступа пользователя, проверьте Session.getCurrentAccessToken.

Пример кода

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    accessToken = AccessToken.getCurrentAccessToken();
}

iOS

Facebook SDK для iOS автоматически управляет маркерами доступа пользователей с помощью класса FBSDKAccessToken. Чтобы узнать больше о получении маркера доступа пользователя, интегрируйте вход через Facebook для iOS. Чтобы получить маркер доступа, проверьте FBSDKAccessToken.currentAccessToken.

Пример кода

- (void)viewDidLoad
{
  [super viewDidLoad];
  NSString *accessToken = [FBSDKAccessToken currentAccessToken];
}

JavaScript

Facebook SDK for Javascript автоматически получает маркеры доступа пользователей и сохраняет их в файлах cookie в браузере. Чтобы получить маркер доступа пользователя, отправьте вызов к FB.getAuthResponse. В ответе будет возвращено свойство accessToken.

Пример кода

FB.getLoginStatus(function(response) {
  if (response.status === 'connected') {
    var accessToken = response.authResponse.accessToken;
  } 
} );

Полный пример кода см. в документации по SDK Facebook для веб-платформы.

Веб-приложение (без JavaScript)

При разработке веб-приложения без использования Facebook SDK for JavaScript маркер доступа нужно будет сгенерировать во время выполнения действий, описанных в соответствующем документе.

Маркеры доступа приложения

Маркеры доступа приложения позволяют отправлять запросы к API Facebook от имени приложения, а не пользователя. С их помощью можно изменять параметры приложения, создавать тестовых пользователей и управлять ими, а также просматривать статистику приложения.

Ограничения

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

Маркеры доступа приложения считаются незащищенными, если для него в дополнительных настройках на Панели приложений установлено свойство Native/Desktop. В этом случае маркеры не будут работать с вызовами API. Дело в том, что нативные приложения или приложения для ПК предположительно содержат встроенный секрет (поэтому маркер доступа приложения, сгенерированный с помощью этого секрета, не является безопасным).

Генерирование маркера доступа приложения

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

• ID вашего приложения;
• секрет вашего приложения.

Пример кода

curl -X GET "https://graph.facebook.com/oauth/access_token
  ?client_id={your-app-id}
  &client_secret={your-app-secret}
  &grant_type=client_credentials"

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

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

Существует ещё один способ отправки вызовов к Graph API, при котором маркер доступа приложения не требуется. Вы можете просто передать ID и секрет приложения как параметр access_token:

curl -i -X GET "https://graph.facebook.com/{api-endpoint}&access_token={your-app_id}|{your-app_secret}"   

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

Маркеры доступа к Страницам

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

Пример кода

curl -i -X GET "https://graph.facebook.com/{your-user-id}/accounts?access_token={user-access-token}" 

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

{
  "data": [
    {
      "access_token": "EAACEdE...",
      "category": "Brand",
      "category_list": [
        {
          "id": "1605186416478696",
          "name": "Brand"
        }
      ],
      "name": "Ash Cat Page",
      "id": "1353269864728879",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    },
    {
      "access_token": "EAACEdE...",
      "category": "Pet Groomer",
      "category_list": [
        {
          "id": "163003840417682",
          "name": "Pet Groomer"
        },
        {
          "id": "2632",
          "name": "Pet"
        }
      ],
      "name": "Unofficial: Tigger the Cat",
      "id": "1755847768034402",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT"
      ]
    }
  ]
}

Маркер доступа к Странице позволяет отправлять вызовы API от имени Страницы. Например, вы можете обновить статус на Странице, а не в хронике пользователя, или просмотреть статистику Страницы.

Маркеры доступа к Страницам уникальны для каждой Страницы, администратора и приложения.

Маркеры доступа клиентов

Как и маркеры приложений, маркеры клиентов позволяют выполнять запросы Graph API от имени приложений, а не пользователей.

В отличие от других маркеров, маркеры доступа клиентов нельзя использовать в запросах самостоятельно: к ним всегда нужно добавлять ID приложения. Для этого добавьте маркер доступа в конце ID приложения, отделив его вертикальной чертой (|):

{app-id}|{client-token}

Пример:

access_token=1234|5678

Чтобы получить маркер доступа клиента для приложения, сделайте следующее:

1. Войдите в свой аккаунт разработчика.
2. На странице приложений выберите приложение, чтобы открыть его панель.
3. На Панели приложений перейдите в раздел Настройки > Дополнительно > Безопасность > Маркер клиента.

Длина маркеров доступа

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

Дополнительная информация

• Список маркеров доступа и информацию об отладке для каждого из них см. в Инструменте маркеров доступа.

• Окончание и продление срока действия

• Отладка и обработка ошибок

• Использование маркеров с приложениями разных типов