Facebook開発者向けドキュメントの日本語訳とTips

http://developers.facebook.com/docs/ に記載されているdocumentationの和訳と、調べていて分かったノウハウを紹介します。
Life is tough, so are we.
ドキュメント全体の目次はこちら
Facebook関連情報はFacebookページで共有しています。

いいね!ボタンの規約違反

前回のエントリーで現在移行中のいいね!ボタンの仕様変更を紹介し、Built-in Likeいいね!ボタンプラグインの違いについて書きました。

そこでは軽く触れただけでしたが、Open Graphアクションとして提供されているBuilt-in Likeは開発者独自の実装となる為、ボタンを自由にカスタマイズできます。反面、いいね!ボタンプラグインは設置が簡単でユーザによる認証も不要な反面、ボタンをカスタマイズすることができません。

今回は以下の3パターンでの規約上の問題について、ボタンのデザインに絞って紹介します。

  • Built-in Likeでいいね!ボタン画像を使う
  • いいね!ボタンのカスタマイズ
  • いいね!以外でのいいね!ボタン画像の利用

Built-in Likeでいいね!ボタン画像を使う

いいね!ボタンの仕様変更を見ると分かる通り、仕様変更後はビルトインのいいね!アクションもいいね!ボタンプラグインもFacebook上での挙動が同じになります。なので、ビルトインのいいね!を自前で実装して、そのボタンに公式いいね!ボタンの画像を使い回しても良いのではないかと思ってしまいます。(同じいいね!なのだからユーザも惑わされないし。)しかし、Built-in Likesドキュメントには以下のような記述があります。
開発者は、クリックできるタイプのいいね!ボタンをデザインすべきです。ブランドガイドラインに従い、このいいね!ボタンはアプリのブランドを使うべきで、Facebookブランドを使ってはいけません。
ですので、Built-in Likeアクションを実装する場合には、ボタンは自前でデザインする必要があります。

いいね!ボタンのカスタマイズ

ブランド情報センターには以下のように書かれています。
「いいね!」ボタンの大きさは必要に応じて調節していただいて構いませんが、その他の変更は一切認められません(デザイン変更など)。
今年5月2日の「エロサイトに「いいね」した人がエロサイトを見ていたとは限らない」で紹介されて話題になりましたが、いいね!ボタンプラグインを故意にカスタマイズしてユーザを騙すことができるようになってしまうので、その対応でもあるようです。ちなみに、下のキャプチャは去年の7月15日に私自身がハマった時のキャプチャです。まりぽさんより1年弱先に投稿しているわけですが、この罠に気付いたのは自分の煩悩のせいです。男って馬鹿ですね。

265087_791104094331_8011726_n

いいね!ボタン以外への利用

また、いいね!以外の目的でいいね!ボタンの画像を使うのも禁止されています。以下、Facebookデザイン プロフェッショナルガイド出版記念のFacebook Power Session 2012でのツイートです。
モバイルウェブだといいね!ボタンが小さくて押しにくいという問題に対して、いいね!ボタン画像を大きくした物にShare LinksのURLを指定へリンクを貼り、それをクリックしてシェアさせるという解決方法が紹介されていて、それが利用規約に違反する恐れがありました。
具体的には以下の通りです。
「いいね!」ボタンは、「いいね!」ボタンのソーシャルプラグイン機能に関してのみ、オンラインで使用できます。
上記ルールがあるため、オンラインではいいね!ボタンプラグイン実装以外にはいいね!画像を使うことができません。シェアでもいいね!でも似た形でニュースフィードに流れるとは言え、いいね!の画像クリックでシェアさせるというのはユーザを騙しているということにもなるので、この実装はかなりマズいのではないかと感じています。
とはいえ、記事へのいいね!数をJS SDKで取ってきてオシャレに表示する方法や、インサイトでいいね!ボタンの統計情報を見る方法などが具体的に紹介されているので、一度読んでみると参考になる点が多いです。

Facebookデザイン プロフェッショナルガイド
Facebookデザイン プロフェッショナルガイド
クチコミを見る



いいね!ボタンに大きめの仕様変更

Open GraphBuilt-in Actionの一つとしてBuilt-in Likeが追加され、モバイルアプリでも簡単にいいね!ボタンを実装できるようになりましたが、これに合わせ、既存のいいね!ボタンの仕様にも変更があるため、アプリによっては大きな影響があります。


各変更の詳細は後述しますが、既存のいいね!に対する仕様変更で一番大きいと思うのは、いいね!されたウェブページを管理するためのFacebookページが作成されなくなる点です。これまでは、いいね!されたウェブページには管理者のみが閲覧できるFacebookページが与えられ、そのウォールへ書き込みを行うことで、いいね!したユーザのニュースフィードへ情報を流すことができました。Open Graph Protocolでは以下のように紹介されています。
Open Graphタグをwebページに含めることで、あなたのページはFacebook Pageと同等の物になります。つまり、ユーザがページ上のLikeボタンを押すと、ページとユーザの間にconnectionが作られます。ページはユーザプロフィールの"Likes and Interests"セクションに表示され、更新情報をユーザへ通知することが可能になります。
ただし、og:typeにarticleを指定したページは対象外という制限がありました。
一時的なコンテンツを象徴するURL(新着記事やブログ投稿、写真、動画など)はarticleを指定してください。websiteを指定してはいけませ ん。websiteやblogはサイト全体を象徴するようにデザインされていますので、og:typeにwebsiteやblogが指定されているページは、通常、ドメインのルート部分にのみ存在すべきです。
(中略)
Open Graph Protocolが実在するオブジェクトをサポートするようにデザインされていることを覚えておいてください。もしも対象URLがコンテンツの一部であるなら(たとえばニュース記事や写真、ビデオなど)、og:typeにはarticleを指定すべきです。articleが指定されたページは、実在するオ ブジェクトではないため先述の情報発信ができませんし、ユーザのプロフィールにも表示されません。
このため、サイトのトップページ(og:type website)をいいね!させることでユーザをこのウェブサイトのファンであると定義し、サイトの更新情報などをファンに対して通知するなどが可能でした。
この機能を利用し、ユーザがトピックを作成するとog:type websiteのページが作成され(このog:type指定の是非はともかく。。)、そこへ新規投稿があるといいね!したユーザのニュースフィードに通知が流れるという実装をした事もあったのですが、それができなくなります。(2012年8月15日追記:管理用のFacebookページを通常のFacebookページへと移行するオプションが追加されました。以下ドキュメント和訳に該当箇所を赤字で追記しています。
  • ユーザは自分の興味ある対象にいいね!する
  • 興味ある物事の最新情報は知りたいはず
という前提で機能してたんじゃないかと思うんですが、ちょっと寂しいですね。

仕様変更後のBuilt-in Likeといいね!ボタンの大まかな違いは以下の通りです。

Built-in Like:

  • 開発者が自由にボタンをデザインできる。
  • 実行にはユーザの認証が必要。

いいね!ボタン:

  • デザイン変更は規約上の制限がある。
  • ユーザの認証無しにも設置できる。
以下、Like button Migrationの和訳ですので、詳細はこちらを参照してください。
Open GraphのBuilt-in Likeアクションリリースに関連して、いいね!ボタンプラグインの仕様を変更します。仕様が完全に移行するまでの間、今後90日の猶予期間内に、開発者はこの移行をテストすることができます。

この移行により、以下の項目が変更されます。

  1. Open Graphオブジェクトに対してBuilt-in Likeアクションが実行できます。以前では不可能で、いいね!ボタンプラグインでのみ可能でした。
  2. 今後、いいね!ボタンをクリックするとBuilt-in Likeアクションが投稿されるようになりますが、ソーシャルプラグインの場合、Auth Dialogを通じてpublish_actionsパーミッションを得る必要がありません。
  3. Open Graphオブジェクトに対して割り当てられていたFacebook管理ページは生成されなくなります。
  4. 管理ページの廃止に伴い、そのOpen Graphオブジェクトをいいね!したユーザに対して告知をすることもできなくなります。REST APIの同等機能も廃止されます。
  5. 既存の管理ページはFacebookページへと移行することができ、このページを通じて今後も更新通知を送ることができるようになります。この方法については後述します。
  6. 管理ページによっていいね!ボタンに年齢制限を付けていた場合は、Object-Level Restrictionsに従ってOpen Graphオブジェクトのog:restrictions:ageメタタグを埋め込むようにしてください。


Preparing for the Migration

いいね!ボタンプラグインを利用しているサイトであれば、移行に際して以下の対応をすべきです。

  1. いいね!ボタンを設置する全Open Graphオブジェクトページは、fb:app_idメタタグをしてください。fb:app_idが無い場合でもいいね!ボタンは機能し続けますが、 app_idを指定する事によって前もって移行をテストする事が可能になります(訳注:移行の猶予期間中は、アプリの管理画面の設定で移行のOn/Off が設定できるので、app_idを埋め込んでアプリといいね!ボタンを紐づける必要がある)
  2. fb:app_idは、紐づいている特定のウェブサイトや製品のアプリケーションIDでなくてはなりません。

いいね!ボタンを持つそれぞれのOpen Graphオブジェクトページは、以下のOpen Graphマークアップが必要になります。

<meta property="fb:app_id" content="[FB App ID]" />

まだ管理ページからの告知機能を利用したい開発者は、以下のタグを含むようにしてください。

<meta property="fb:app_id" content="[FB App ID]" />
<meta property="fb:admins" content="[FB UIDs of FB App Admins]" />

これにより、Open Graphオブジェクトページに管理ページへのリンクが表示されます。いいね!ボタンに紐づく管理ページへのアクセスは、ここからでも可能です。

その後、サイトや製品を表すFacebookページを別個に作成してください。それから既存の管理ページにウォール投稿し、新しく作ったFacebook ページをいいね!するようユーザに働きかけます。これにより、いいね!の移行完了後も新規Facebookページを通じてユーザとコミュニケーションを取る事ができます。もしくは、既存の管理ページをFacebookページへと移行することも可能ですので、その方法は後述します。

管理ページを通じてユーザ制限を設けていた場合は、Object-Level RestrictionsメタタグをOpen Graphオブジェクトに埋め込んで対応してください。これらのメタタグは年齢、国籍、content-typeを基にして、対象ユーザへのいいね!ボタン閲覧の可否、ニュースフィード投稿閲覧の可否をコントロールします。

既存のいいね!ボタンのカウントが変わる事はなく、ここまでで紹介された変更以外の点で影響を受ける事はありません。


Testing the Migration

90日間の猶予期間内にこの移行をテストするには、まずいいね!ボタンを配置している全Open Grpahオブジェクトのページでfb:app_idメタタグを指定しなくてはなりません。これまでfb:app_idメタタグを設置していなかった Open Graphオブジェクトページに関しては、scrapper APIを使って再度Facebookにスクレイピングさせる必要があります。

それが完了したら、アプリの管理画面へ行き、Settings > AdvancedセクションのMigrationsにある"External Page Migration"を設定します。

LikeButtonMigrationSetting

この"External Page Migration"は、すでにいいね!ボタンが設置されている場合はデフォルトでDisabledになっています。ここをEnabledに変更することで上記で説明した変更点を有効にできます。猶予期間内であれば何度でもEnabled / Disabledを切り替えることが可能です。


Converting an Admin Page to a Facebook Page

移行後は、いいね!ボタン用の既存の管理ページは廃止され、いいね!したユーザへの更新通知目的での利用ができなくなります。また、REST APIのエンドポイントも同様に廃止されます。

そのかわり、移行期間中であれば既存の管理ページはFacebookページへと移行可能で、これまでのいいね!の数も新しいFacebookページへと引き継がれます。また、いいね!ボタンの向き先もこちらへと変わります。

管理ページをFacebookページへと移行する手順は以下の通りです。

  1. アプリの設定画面で"External Page Migration"を有効にする
  2. https://www.facebook.com/bookmarks/pagesにアクセスして管理ページを選択する
  3. 管理ページへ遷移したら、"Migrate Your Page"というタイトルで下のキャプチャのように表示される部分に注意してください。ここの"Migrate Page"を選択することで、既存の管理ページをFacebookページへと移行できます。

Migration_Banner


確認用ダイアログが以下のように表示され、移行完了後に行うことのレコメンドが表示されます。

Post-Convert

Facebookページへの移行が完了したら、それを正しく設定する為に以下のステップを踏むべきです。

  • 既存のいいね!ボタンのhref値をFacebookページのものに置き換える
  • 適切なページ名、カバー画像、プロフィール画像を設定する
  • ページの独自URLを設定する。詳細はこちらを参照してください。

Migration-Complete



Event APIの時刻表記に仕様変更

今朝の開発ブログ「Platform Migration: Events Timezone Support」で正式に発表されましたが、イベント系のGraph APIオブジェクトとFQLテーブルに仕様変更があります。これは新規作成されるアプリ、アプリ管理画面のAdvanced > Migrations > Events Timezonesを有効にしたアプリに適用され、90日の猶予後には全アプリへと適用されます。


以下、変更内容です。

FQL:

eventevent_memberテーブル

  • Pasific TimeのUNIXタイムスタンプだったstart_timeとend_timeフィールドがISO-8601形式の表記に。
  • 必ず定義されていたend_timeがそうではなくなる。

Graph API 読み込み

Eventオブジェクト

  • offset値無しのISO-8601形式で返されていたstart_timeとend_timeがISO-8601形式に。
  • date_formatパラメータで返すフォーマットを指定できたが、できなくなる。
  • 必ず定義されていたend_timeがそうではなくなる。

Graph API 書き込み

Userオブジェクト

  • strotimeで変換できる形式ならば受け付けていたstart_timeとend_timeがISO-8601形式のみ受け付けるようになる。
    例:日付のみなら'2012-07-04'、厳密な時刻(UTC)なら'2012-07-04T19:00:00-0700'

FacebookがCrunchUpに参加

開発ブログで、8月3日にTechCrunchが主催するCrunchUpにFacebookが参加することが発表されました。今年はf8の話題が全然でないなぁと思っていたんですが、これが代わりになりそうですね。扱うのは、プラットフォーム、モバイル、広告についての話題。オフィスアワーもあるので、Facebookの担当者と直に接する機会が持てそうです。

eventbriteでチケット販売されていて、CrunchUpとパーティ込みのチケットのみ残っています(8:00現在)。


開催日時:
8月3日

場所:
Readwood CityのFox Theater

アジェンダ:

12:00 PM Registration and Lunch
1:00 PM Welcome
1:10 PM Fireside Chat with Mike Schroepfer – Vice President of Engineering – Facebook
1:40 PM Product Tour – Peter Deng – Director of Product Management – Facebook
1:55 PM Panel: Designing and Growing a Modern Mobile App
2:20 PM Break
2:40 PM Product Tour – Doug Purdy – Director of Developer Products – Facebook
3:05 PM Panel: What’s Next For Facebook’s Platform
3:30 PM Panel: Social Ads: What’s Working, What’s Not, and Where’s Everyone Else?
4:00 PM Office Hours and Happy Hour with Facebook


パーティ:

5:30 PM - 9:00 PM パーティ込みのチケットの場合のみ参加OK

Graph API, FQLのページングの罠

Graph APIやFQLでユーザの投稿一覧やフィードを取得しようとしていると、特にoffsetとlimitを使ったページングで上手く行かないことがあります。シェアボタン廃止前後のメモを探しているうちに、去年の春頃に自分でハマったときの記録が出てきたので共有します。
ただ、去年3月の公式ブログ記事の内容を基にしてるので、現状どうなってるのかは試してないです。(常に最新状態に更新されるドキュメントと違って、ブログ記事だと後からのフォローが分かりにくいですね。ドキュメントも最新じゃないこと多いですが。。)


Graph APIやFQLでlimitを使って検索した場合、Facebook側では対象期間中の全件をまず取得し、そこから閲覧権限のあるオブジェクトのみを返すという動作をします。以下の画像は公式ブログからの引用ですが、途中で閲覧権限外のオブジェクトが間引かれているのが分かります。
attachment
このため、上図のケースでoffset=3を指定しても返されませんし、limit=10でも10件は返されません。対応策として紹介されているのは、offsetの代わりにsince,untilとlimitを組み合わせて使う方法です。時系列に検索する場合は、取得したオブジェクト群の最後の1つのtimestampをsinceに指定し、逆時系列の場合はuntilを使います。

Graph API:https://graph.facebook.com/chickfila/posts?until=1298508006
FQL:SELECT message, created_time FROM stream WHERE source_id = XXXXXXXX AND created_time < 1299634732


ただし、since,untilとlimitを組み合わせた場合でも一件も返されなかい場合はあり、それが最後のページングだったのか、それとも対象全件が閲覧権限外だっただけでまだ残りがあるのか判別しなくてはならないという問題が残ります。その際には、limitの値を大きくして試すなどの方法が紹介されています。その際のヒントとして、閲覧権限をチェックして間引く前に検索できる最大件数(要するにlimitの最大値で、上図で言うと左の状態)は5000件だと書かれています。

Graph APIでこれらの対応が必要となるのは、以下のフィールドやコネクションです。
checkins, feed, home, links, notes, photos, posts, statuses, tagged, videos
FQLであれば、以下のテーブルです。
checkin, status, stream
このページング問題とは別に、Graph APIの /USER_ID/home は直近1~2週間分のオブジェクトしか返さないことに気をつけてください。(この点は2012年4月30日更新のドキュメントで確認済みです。)
記事検索