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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Маркеры доступа пользователя бывают двух видов: краткосрочные и длительного действия. Краткосрочные маркеры обычно действуют около часа или двух, тогда как срок действия маркеров длительного действия составляет около 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 для JavaScript автоматически получает и сохраняет маркеры доступа пользователя в файлах cookie в браузере. Чтобы получить маркер доступа пользователя, можно отправить вызов FB.getAuthResponse и получить в ответе свойство accessToken.

Пример кода

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

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

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

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

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

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

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

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

{app-id}|{client-token}

Пример:

access_token=1234|5678

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

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

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