Маркеры доступа

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

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

Тип маркера доступаОписание

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

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

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

Этот маркер доступа позволяет считывать и изменять настройки приложения. Его также можно применять для публикации действий Open Graph. Этот маркер генерируется с использованием секрета, заранее согласованного между приложением и Facebook, и затем используется в вызовах, изменяющих настройки всего приложения. Для получения маркера доступа приложения нужно отправить вызов с сервера на сервер.

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

Он похож на маркер доступа пользователя, но разрешает API считывать, записывать или изменять данные, принадлежащие Странице Facebook. Если вам нужен маркер доступа к Странице, следует сначала получить маркер доступа пользователя и запросить разрешения для Страницы. Получив маркер доступа пользователя, вы можете получить маркер доступа к Странице через API Graph.

Маркер клиента

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

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

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

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

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

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

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

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

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

Важно понимать, что маркеры доступа можно переносить. Получив маркер доступа, вы можете применять его в вызовах к серверам 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. Дело в том, что нативные приложения или приложения для ПК предположительно содержат встроенный секрет (поэтому маркер доступа приложения, сгенерированный с помощью этого секрета, не является безопасным).

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

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

Пример кода

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 можно выполнять только с помощью серверного кода.

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

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

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

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

Эти маркеры используются в вызовах API Graph для управления Страницами 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 от имени Страницы. Например, вы можете обновить статус на Странице, а не в хронике пользователя, или просмотреть статистику Страницы.

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

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

Начиная с версии SDK 13.0 для iOS и Android, которая должна выйти в начале 2022 г., для всех вызовов API Graph будет необходим маркер клиента.

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

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

{app-id}|{client-token}

Пример:

access_token=1234|5678

Чтобы получить маркер доступа клиента, войдите на Панель приложений и перейдите в раздел Настройки > Дополнительно > Безопасность > Маркер клиента.

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

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