facebookのoffline access の削除まとめ

facebookのドキュメント漁り。

特にoffline access まわりと、access tokenの各種エラー周りを、対訳ぽく。

ちなみにこの情報は、2012/7/29時点のもの。

既存のドキュメントもupdateされたりするので、注意が必要。

最初にまとめ。

• offline access permissionは、現時点では、deprecatedからremovalにステータスが進んでいる。
• • 7/5に予定されていたものが、10/3に変更になっている。
• アプリの設定画面での項目は、deprecate offline_accessからRemove offline_access permissionになっている
• この項目を「有効にする」ことで、動作が変わる
• • "長い有効期限"のaccess tokenが使えるようになる。
  • • offline access permissionを使っていたかどうかに関わらず。
  • 新しいユーザーの認証ダイアログに、offline permissionは表示されなくなる。
  • すでに取得している期限なしのoffline access tokenは、そのまま。
  • • 10/3(現時点の公表日)を過ぎると60日に切り詰められる
  • Server side OAuth で得られるaccess tokenは長い期限の方。
  • • しかし、その取得にはauthorization codeが必要なので、結果、cronなどで勝手に延長することはできない。
  • Client side OAuth の場合は、access tokenを"交換"する
  • • 長い期限のaccess tokenが得られる。が、長いものを投げても延長されない。
• APIが400のエラーから返るケースにうまく対処する方法がある(PHPの実装例あり)

https://developers.facebook.com/docs/authentication/

Authentication

Core Concepts › Authentication

Please note: On October 3, 2012, the offline_access permission will be removed. If you are building a new application you shouldn't use this permission. Instead please check the Deprecation of Offline Access Permission document which explains how to start using access tokens that are valid for up to 60 days.

2012/10/3にofflice_accessのpermissionは削除される。
新しいアプリケーションを作成中ならこのpermissionは利用すべきではない。
代わりに、60日有効なaccess tokenの使い方を説明しているDeprecation of Offline Access Permission(offline access permissionの廃止予定)を確認のこと。
(訳注：リンク先の
https://developers.facebook.com/docs/offline-access-deprecation/
は、2012/7/29現在では、
https://developers.facebook.com/roadmap/offline-access-removal/ にリダイレクトされる。
廃止予定から、削除に格上げされているよう。）

https://developers.facebook.com/roadmap/offline-access-removal/

Removal of offline_access permission

Access_tokens allow users to interact with your apps in secure and social ways. While we are removing the use of the offline_access permission, through a migration setting in the Developer App, we are now allowing the option to use access_tokens with a long-lived expiration time that can be renewed each time the user revists your app (see exceptions below). For existing apps that are not using the offline_access permission, there are no changes required for your app, but you should consider using the new endpoint that allows the longer expiration time.

access tokenによって、ユーザーとあなたのアプリは安全かつソーシャルにやり取りできる。我々は、offline access permissioinを削除しようとしているが、現在は、ユーザーがあなたのappを訪れるたびに(例外は後程)更新されうる"長い有効期限の"access tokenを利用するオプションをDevelper appsの移行設定にて提供している。
offline access permissionを利用していない提供済みのappは、何も変更しなくてよいが、より有効期限の長い新しいendpoint(訳注：APIの種類)を利用することを検討すべきだ。

Extending the expiration of existing short-lived user access_tokens

発行済みの"短い有効期限の"ユーザー access tokenの延長に対応する

When a user visits your site with an existing, valid, short-lived user access_token, you have the option to extend the expiration time of that access token. Our platform will only extend the expiration time once per day, so even if a user revists your site multiple times a day, the token will be extended the first time requested. You must make sure to call the new endpoint below before the short-lived access_token expires. Currently the long-lived user access_token will be valid for 60 days while the short-lived user access_tokens are currently valid from 1 to 2 hours.

ユーザーが、発行済みの、有効な、"短い有効期限の"ユーザー access tokenであなたのサイトに訪問した際、そのaccess tokenの有効期限を延長することを選択できる。
我々のplatformでは、1日1回だけしか有効期限を延長しないので、ユーザーが1日に複数回再訪した際には、初回の要求で、tokenが延長される。
"短い有効期限の"access tokenが切れる前に、後程説明する新しいendpointを呼ばなければならない。
現在、"短い有効期限の"ユーザーaccess tokenが1~2時間有効なのに対して、"長い有効期限の"ユーザーaccess tokenは60日間有効である。

Some Exceptions

例外

Exception 1: Desktop Apps

Once the migration setting has been enabled, Desktop applications will automatically get user access_tokens returned that have the longer expiration time. However, there is no way to get a long-lived user access_token without having the user login to your app again.

例外その1：デスクトップapp
デスクトップappへの移行設定が有効にされると、デスクトップappは、自動でより長い有効期限のaccess tokenを自動的に得る。
しかし、ユーザーがappに再度ログインしないと、長い有効期限のユーザーaccess tokenは得られない。

Exception 2: Native Mobile Apps using older SDKs (iOS and Android)

We released an update to our SDKs for iPhone and Android that will allow access_token expiration to be extended. If you continue to use an older version, and do not implement changes to extend the token, the user will have to re-login to your app periodically when the access_token expires. See the iOS and Android doc pages for more information:

• iOS: https://developers.facebook.com/docs/mobile/ios/build/#extend_token
• Android: https://developers.facebook.com/docs/mobile/android/build/#extend_token

例外その2：古いSDKを利用したiOS/androidのネイティブアプリ
access tokenを延長できるiPhone/android向けの新しいSDKをリリースした。
古いバージョンのSKDを使い続け、tokenの延長処理の変更を実装しないのなら、ユーザーは時折、access tokenが有効期限切れした場合には再ログインしないといけない。iOSとandroidのドキュメントを参照のこと

Exception 3: Native Mobile Apps using newer SDKs (iOS and Android)

Once the migration setting has been enabled, mobile applications using our newer SDKs will automatically be granted a user access_token with the longer expiration, you do not have to do anything to get this extended. Also, each day a user revisits your app, you will be granted a new user access_token with a fresh expiration time. Note: Each day, the access_token returned may or may not be the same access_token as the previous day.

例外その3：移行設定が一度有効にされると、新しいSDKを利用したモバイルアプリは、自動的により長い有効期限のユーザーaccess tokenを与えらえる。この拡張を利用するために何もする必要はない。
同時に、あなたのアプリに再訪した日ごとに、新たな有効期限のユーザーaccess tokenを与えらえる。
得られるaccess tokenは前日と同じかもしれないし、違うかもしれないことに注意。

Getting started with the new migration setting

新しい移行設定を始めよう

You will see a new migration called "deprecate offline_access" in your Advanced settings of the Developer App. Enable it and click "Save Changes" for the migration to take effect for that app. After the migration is enabled, apps can create and extend access tokens under the new token model. Additionally, if you were previously requesting the offline_access permission, that permission will no longer be displayed in the Auth Dialog to new users.

Developer Appの詳細設定には、"deprecate offline access"という項目がある。
(訳注：2012/7/29現在、この設定項目は、このページのキャプチャには入っているが実際のページにはない)
有効にして、変更を保存を押すと、移行設定がそのアプリに影響する。移行設定を有効にしたのち、アプリは新しいtokenモデルのもと、access tokenを作成、延長できる。加えて、それまでoffline access permissionをユーザーに求めていたのなら、新しいユーザーの認証ダイアログにはもはやofflien access permissionは表示されない。

Scenario 1: If you were NOT previously asking for offline_access

There are no required changes needed for your app to continue functioning. If you were obtaining user access_tokens through the signed_requests or those returned in a browser hash-tag (client-side), those tokens will have short expirations. You should consider using our new endpoint to exchange them for new access_tokens that have a longer expiration time. When you do the exchange, your short-lived access_token will continue to function until it expires, however, the new endpoint will return a second access_token that will have a much longer expiration and this is what you should use going forward.

シナリオ1：以前にはoffline accessを要求していないかった場合、あなたのアプリが機能し続けるための変更は何も必要ない。
signed requestを元にユーザーaccess tokenを取得していた、または、クライアント側でのbrowser hash-tag(訳注：このパターンは知らないので自信ない)にて戻されたsigned requestを元にユーザーaccess tokenを取得していたのなら、それらのtokenは短い有効期限のものである。
より長い有効期限の新しいaccess tokenと交換してくれる新しいendpointを利用することを検討すべきだ。交換すると、短い有効期限のaccess tokenはその有効期限までは有効だが、新しいendpointはより長い有効期限の”別の”access tokenを返すのでそちらを優先して利用すべきだ。

Scenario 2: If you have been previously requesting offline_access - updated 4/30/2012

Once the migration has been enabled, existing use access_tokens, with the offline_access permission, will continue to work without any change to their expiration time. However, new users to your app will not be prompted for the offline_access permission in the Auth Dialog and will receive either a short-lived or long-lived access_token depending on your environment and how you are requesting the access_token (client or server-side OAuth, see Scenario 3 and 4 below).

After the offline_access removal date (see roadmap for exact date), all existing offline_access access_tokens will have their expiration time truncated to 60 days. This truncation will be transparent to the user and your app will continue functioning normally; Facebook will send an updated message through the weekly developer round-up when this truncation will occur.

シナリオ2：(2012/4/30更新)以前に、offline accessを要求していた場合。
移行設定が一度有効になると、すでに発行済みの、offline access permissionを含むユーザーaccess token(訳注：useはuserの誤字と思われ)は、”その有効期限は全く変わらず有効であり続ける”
しかし、新しいユーザーには、認証ダイアログにてoffline access permissionは表示されず、あなたの環境と、どうやって要求しているか(クライアント側かサーバー側のOauthか(シナリオ3,4を参照))によって、短い有効期限か長い有効期限のどちらかのaccess tokenを受け取る。
offline accessの削除の日(正確な日時はroadmapを見てね)以降は、発行済みのoffline accessを含むaccess_tokenはすべて、60日の有効期限に切り詰められる。
この切り詰めは、透過的に(訳注：影響なく)行われ、ユーザーとあなたのappは通常通り動作し続ける。
我々は、この切り詰めが行われたのち、weekly developer round-upを通じて更新通知を送る予定だ。

Scenario 3: Server-side OAuth Developers

Once the migration is enabled, if the access_token is generated from a server-side OAuth call, the resulting access_token will have the longer expiration time by default. If the call is made while there is still a valid long-lived user access_token for that user, the returned user access_token from this second call may be the same or may have changed, but in either case the expiration time will be set to a long expiration time.

Note: The user must access your application before you're able to get a valid "authorization Code" to be able to make the server-side OAuth call again. Apps will not be able to setup a background/cron job that tries to automatically extend the expiration time, because the "authorization code" is short-lived and will have expired.

シナリオ3：サーバー側OAuthで開発している場合
この移行設定が有効になると、サーバー側OAuthの呼び出しにて生成されたaccess tokenは、デフォルトで長い有効期限のものである。
サーバー側OAuthの呼び出しが、そのユーザーのユーザーaccess tokenが長い有効期限のものであり、かつまだ有効な間に行われた場合、
戻されるユーザーaccess tokenは同じものかもしれないし、違うものかもしれないが、どちらにせよ、長い有効期限のものである。
注意：サーバー側OAuthを実行するために必要な"認可コード"を得る前に、ユーザーがあなたのアプリにアクセスしていないといけない。アプリはbackgroundやcron実行によって自動的に有機現を延長するようにすることはできない。なぜなら、"認可コード"は短い有効期限で期限切れするからだ。

Scenario 4: Client-side OAuth and Extending Access_Token Expiration Time through New Endpoint

Using the new endpoint below, you will be able to extend the expiration time of an existing, non-expired, short-lived user access_token. Please note, the endpoint can only be used to extend the short-lived user access_tokens. If you pass an access_token that had a long-lived expiration time, the endpoint will simply pass that same access_token back to you without altering or extending the expiration time.

シナリオ4：クライアント側OAtuhを利用していて、新しいendpointを用いて access tokenの延長を行う場合
後述の新しいendpointを用いると、発行済みで有効期限内の短い有効期限のaccess tokenの有効期限を延長することができる。
このendpointは、短い有効期限のaccess tokenを延長するためだけに使えることに注意。
長い有効期限のaccess tokenを投げても、endpointは同じaccess tokenを返すだけであり、有効期限を延長もしないし何も警告しない。

To get the long-lived user access_token simply pass your own client_id (your app_id), your app_secret, and the non-expired, short-lived access_token to the endpoint below. You will be returned a new long-lived user access_token; this access_token will exist in addition to the short-lived access_token that was passed into the endpoint. If you would like to refresh a still valid long-lived access_token, you will have to get a new short-lived user access_token first and then call the same endpoint below. The returned access_token will have a fresh long-lived expiration time, however, the access_token itself may or may not be the same as the previously granted long-lived access_token.

長い有効期限のユーザーaccess tokenを簡単に得るためには、あなたのclient_id(app_id)とapp_secretと、期限切れしていない短い有効期限のaccess tokenをendpointに渡せばよい。
長い有効期限のユーザーaccess tokenが返される。この(訳注：長い有効期限の)access tokenは、endpointに渡された短い有効期限のaccess tokenに加えて存在しうる(訳注：新たに発行される)
もし、長い有効期限のaccess tokenを更新したいのなら、まず短い有効期限のaccess_tokenを新たに取得し、そしてendpointを呼び出すこと。
返ってきたaccess tokenは、新たな長い有効期限のものだ。しかし、前に与えられた(訳注：長い有効期限の)access tokenと同じかもしれないし、違うかもしれない。

https://graph.facebook.com/oauth/access_token?             

    client_id=APP_ID&

    client_secret=APP_SECRET&

    grant_type=fb_exchange_token&

    fb_exchange_token=EXISTING_ACCESS_TOKEN 

Scenario 5: Page Access Tokens

When a user grants an app the manage_pages permission, the app is able to obtain page access tokens for pages that the user administers by querying the [User ID]/accounts Graph API endpoint. With the migration enabled, when using a short-lived user access token to query this endpoint, the page access tokens obtained are short-lived as well.

Exchange the short-lived user access token for a long-lived access token using the endpoint and steps explained earlier. By using a long-lived user access token, querying the [User ID]/accounts endpoint will now provide page access tokens that do not expire for pages that a user manages. This will also apply when querying with a non-expiring user access token obtained through the deprecated offline_access permission.

シナリオ5：ページaccess token
ユーザーが、アプリに対してmanage_pageのpermissionを許可している場合、アプリは、[UserID]/accounts のGraph API endpointによって得られる、そのユーザーが管理しているページのページaccess tokenを得ることができる。この移行が有効になると、このendpointに対して、短い有効期限のユーザーaccess tokenを利用すると、得られるページaccess tokenも短い有効期限のものとなる。
すでに説明したようなステップで、endopointによって短い有効期限のaccess tokenを、長い有効期限のaccess tokenと交換しなさい。

長い有効期限のユーザーaccess tokenを用いれば、[UserID]/accountsのendpointは、そのユーザーが管理しているページに対して"期限切れしない"ページaccess tokenを提供してくれる。これは、廃止されるoffline access permission から得られた、期限切れしないユーザーaccess tokenで要求した場合にも適用される。