アクションとは、ユーザがアプリケーション上でとることができる社会的行動です。アクションを生成する前に、Dev AppでObjectsとActionsを定義してください
- Creating Actions
- Reading Actions
- Updating an Action
- Deleting an Action
- Commenting on an Action
- Liking an Action
- Configure Action Timestamps
Creating Actions
アクションはDev Appを用いて定義します。アクションが定義されると、アプリケーションはAPIを用いてアクションのインスタンスを生成できるようになります。これによってユーザとオブジェクトのインスタンスの間の繋がりが成り立ちます。
POST /me/{namespace}:{action-type-name}以下のAPI呼び出しでは、閲覧ユーザとPumpkin Pie(recipebox:cookのオブジェクトインスタンス)との間に「読んだ(read)」という繋がりを作ります。
https://graph.facebook.com/me/recipebox:cook? recipe=http://www.example.com/pumpkinpie.html&access_token=YOUR_ACCESS_TOKEN
注意 - App Access Tokenを用いて、認証されたユーザのアクションを投稿することも可能です。アクションが投稿されると、友人のニュースフィードやリアルタイムフィードに流れます。
ニュースフィード上
リアルタイムフィード上
Previewing Stories from Published Actions
生成されるアクションは、https://www.facebook.com/USER_ID/activity/STORY_ID
, where USER_IDでプレビューできます。USER_IDにはユーザのFacebook IDもしくはusernameが入り、STORY_IDにはいかに説明するaction-instance-idが入ります。
例えば以下のようなURLになります
https://www.facebook.com/dhirenp/activity/10100657260775943
プレビューを確認するには、ユーザはアプリケーションに対して適切なパーミッションを与えていなくてはなりません。
Required Parameters
Name | Value | Type |
property_name | URLもしくはグラフ上のオブジェクトID 該当URLのオブジェクトがグラフ上に存在しない場合、スクレイピングの対象となります。 | string |
Optional Parameters
Name | Value | Type |
start_time | アクション開始時刻 | ISO-8601 date-time |
end_time | アクション終了時刻 | ISO-8601 date-time |
expires_in | アクションが「古い」とみなされるまでの秒数。この秒数が経過するまではアクションは「現在形」で扱われ、それ以降は「過去形」となります。 expires_inは、アクション開始から終了までの期間を秒数で求めるほうが便利な場合に、end_time指定の代わりともなります。例えば、ユーザが映画を見始めたときのwatchアクションを投稿するとき、expires_inは映画の上映時間の秒数です。 | integer |
place | アクションをとった場所を示すIDです。たとえばSimon ate Pizza at Facebook HQです。 | id |
tags | アクションに紐づけられた人物のIDです。たとえば、Carl, Vlad, and Paul visited Dolores Parkです。 | a string of comma separated ids |
ref | Facebook上に表示されるOpen Graphアクションをクリックしてサイトへ流入するとき、fb_refパラメータが渡されます。これはA/Bテストや、アクションに関連するデータをトラッキングする際に有用です。 デフォルトでは、refパラメータは7日間500個のユニークな値を受け付けます。insight上ではこれらの値毎にグルーピングされたグラフが表示されます。 7日間中で500個よりも多い値が必要な場合、たとえばrefパラメータにユニークIDを渡す場合などは、__セパレータを用いることができます。このセパレータの左側の文字列はInsightsでインデックスとして用いられ、A/Bテストの結果を解析する助けとなります。セパレータの右側にある文字列はInsightsでは無視され、7日間500個の勘定に入りませんが、ユーザがOpen Graphアクションのリンクから導入する際にはfb_refパラメータで渡されます。 | string |
scrape | trueが指定された場合、アクションを生成する前にオブジェクトをスクレイピングしてプロパティを更新します。スクレイピングするのでレスポンスが遅くなりますから、オブジェクトが更新された場合に飲みスクレイピングさせてください。 | bool |
Response
{ id: “{action-instance-id}” }
Action typeで定義されていない追加プロパティが送られてきた場合、エラーが返されます。
Setting custom action instance properties
アクションのインスタンスが生成されるときには必ずカスタムアクションプロパティがセットされなくてはなりません。下記のような形式でパラメータを指定します。
{custom-property-name}={value}
以下の例が、カスタムプロパティ(recipebox:cookアクションのrating)のセット方法を示しています。
https://graph.facebook.com/me/recipebox:cook? book=http://www.example.com/pumpkinpie.html&rating=10
Tagging people and places
アクションはplace,tagsパラメータの指定によって、場所や人物をタグ付けすることができます。以下のパラメータで、Zhen read The Great Gatsby with Austin and Vlad at Ritual Coffee Roasters on Readlyというアクションが生成されます。
tags
- Facebook User IDをカンマ区切りで。place
- アクションが起こった場所のPage ID。Graph APIを用いてPLACE IDを検索できます。type=placeを指定する
- クエリパラメータのqを指定
distanceは必須ではありません
https://graph.facebook.com/search? q=coffee& type=place& center=37.76,122.427& distance=1000
https://graph.facebook.com/me/recipebox:cook? book=http://www.example.com/pumpkinpie.html& place=145768288146& tags=208576,507763995&access_token=YOUR_ACCESS_TOKEN
Reading an Action
アプリケーションを認可したユーザのアクションを読み取ることも可能です。例えば、Recipeアプリケーションは私が料理/計画したレシピを読み取り、そのデータを元にアプリケーション体験をカスタマイズできます。このAPIは、タイムスタンプやカスタムプロパティとその値などのメタデータを返します。アクションから参照されるオブジェクトは一階層の深さで返されます。
GET /{action-instance-id}
下記のように任意のアクションインスタンスを取得します
https://graph.facebook.com/1538292028372 ?access_token=USER_ACCESS_TOKEN
Response
{ "id": "1538292028372" "start_time": 1303502229, "end_time": 1303513029, "data": { "type": "recipebox:recipe", "url": "http://www.example.com/pumpkinpie.html", "id": "1234567890", "title": "Pumpkin Pie" }, }
Note watch/news.read(Social Barにより投稿されるアクション)を指定することにより、ビルトインアクションを探すこともできます。
Updating an Action
下記のようにしてアクションインスタンスのプロパティを更新することも可能です。
POST /{action-instance-id}
下記のサンプルではアクションのend_timeを更新しています。
https://graph.facebook.com/1538292028372?expires_in=300 &access_token=YOUR_ACCESS_TOKEN
Response
true
Deleting an Action
アプリケーションを認可したユーザのアクションを削除することも可能です。ユーザが遡ってアクティビティを削除しようとする場合に使ってください。ユーザコントロールのベストプラクティスに関してはOpen Graph Best Practices Guideをご覧ください。
DELETE /{action-instance-id}
以下のサンプルはアクションインスタンス1538292028372を削除します。
https://graph.facebook.com/1538292028372?&access_token=YOUR_ACCESS_TOKEN
Response
true
Liking an Action
任意のアクションとユーザの間にLikeコネクションを生成します。POST /{action-instance-id}/likes
以下のサンプルはユーザとアクションインスタンス1538292028372のあいだにLikeコネクションを生成しています。
https://graph.facebook.com/1538292028372/likes ?&access_token=YOUR_ACCESS_TOKEN
アクションインスタンスに紐づいたlikeを取得するには以下のようにします。
GET /{action-instance-id}/likes
Commenting on an Action
任意のアクションにユーザのコメントを追加するには以下のようにします。
POST /{action-instance-id}/comments
任意のアクションに対するユーザのコメントを取得するには以下のようにします。
GET /{action-instance-id}/comments
アクションのコメントを取得する詳細については、こちらで解説されています。
Timestamps
Action’s timestamps can be configured to describe actions that occur at different times and how actions appear on the user's profile and News Feed.
アクションのタイムスタンプは、アクションが異なる時刻に発生したり、ユーザのプロフィールやニュースフィードでどのように表示されるかを決定します。
Supported configurations for timestamps are:
タイムスタンプの設定でサポートされているのは以下の通りです。
- API呼び出しが行われた時刻(デフォルト。例:投票など)
- 過去に開始し、過去に終了する(例:去年の夏にプレーしたサッカーチーム)
- 過去に開始し、未来に終了する(例:学期中に生徒が受講するクラス)
- 現在開始し、未来に終了する(例:交際ステータス)
- 現在開始し、終了は不定(例:「いいね!」や「欲しい」)
end_time = start_time + expires_in
旅行が長引いたとかクラスの受講を止めるなどでアクションのend_timeが変更する場合は、end_timeを更新できます。
Timestamps and collections
タイムスタンプを用いてアクションの状態を確かめることで、集合を形成することができます。例えば、start_dateが過去でend_dateが未来のenrolledアクションを取得することで、生徒が現在履修中のクラスの集合を取得できます。同様にして、1998年の3月に私が履修していたクラスを、start_dateがMarch 1, 1998以前でend_dateがMarch 31, 1998以降のenrolledアクションを探すことで取得できます。
この方法を用いて、"like"や"want"などの恒久的なアクションの集合を求めることも可能です。