最新のTwitter@Anywhere公式ドキュメントの日本語訳

2012/05/19 12:21:10

検索して出てくる解説サイトや、日本語訳が若干古かったので、現時点での最新版をもう一度訳してみました。
最終の更新日付は、2012年01月09日だそうです。

@Anywhereって実はすごく便利やと思ってるのですが、あんまり使われてないです・・よね？
サーバーサイドわからん！って人でも、簡単に導入できるのでぜひぜひ試してみてください！

随時注釈を挟んで、本家よりわかりやすくした・・つもりですｗ

参考：Welcome to @Anywhere | Twitter Developers

@Anywhereをはじめる

@Anywhereを使うことで、あなたのサイトにTwitterの機能をすごく簡単に組み込むことができます。
@Anywhereは、サイト利用者を増やすのに一役買うことでしょう。
@Anywhereは、フォローボタンの追加、ホバーカードの表示や、Twitterのユーザー名のオートリンクの他、Connect to Twitterといった高度な機能も提供します。

ページ内の@hogehogeを勝手にリンクにしてくれたり、マウス乗せるとプロフィールが表示されたりするやつを見たことありませんか？あれです、あれ。
その他ツイートできるフォームやら、フォローボタン、果てにはログイン機構までできちゃう。
しかも全部JavaScript！それが＠Anywhereです。

まずはじめに

まずはじめに、アプリケーションの登録が必要です。
既に他のアプリケーションを登録している場合も、@Anywhere用に新しく登録することをオススメします。

登録時のコールバックURLは、サブドメイン、ドメイン共に@Anywhere用に登録したURLと一致している必要があります。

意外に面倒なアプリ登録ですが、作業と割りきって淡々と。
Consumer Keyと、Consumer Secretは後で使いますのでメモ

@Anywhereを使いたいHTMLページで、JavaScriptを読み込みます。
@Anywhereのjsファイル読み込みに関しては、出来る限りページ上部に記述することをオススメします。(理由は後述)
"Consumer Secret"に関しては、もしかしたら使う機会があるかもしれません。ただくれぐれも、HTMLやJavaScriptの中に"Consumer Secret"を記述しないようにしてください。

<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
    <title>Anywhere Sample</title>
    <script src="http://platform.twitter.com/anywhere.js?id={YOUR_CONSUMER_KEY}&v=1"></script>
  </head>
  <body>
    ...
  </body>
</html>

このjsファイルは、グローバルオブジェクトとしてtwttr変数のみを展開します。
この変数のanywhereメソッドを呼び出しコールバックを利用することで、それぞれの機能を使うことができます。
コールバックには、APIクライアント(以下ではT)を単一の引数として渡します。
このAPIクライアントが、すべての@Anywhereの機能を保持しています。
ホバーカードを表示するサンプルを以下に示します。

使用例

twttr.anywhere(function (T) {
  T.hovercards();
});

anywhereメソッドは、単一ページ内で何度も呼び出すことができます。
以下は、ホバーカードとフォローボタンを同時に使用するサンプルです。

<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
    <title>Anywhere Sample</title>
    <script src="http://platform.twitter.com/anywhere.js?id=YOUR_API_KEY&v=1" type="text/javascript"></script>
  </head>
  <body>
  <script type="text/javascript">
    twttr.anywhere(function (T) {
      T.hovercards();
    });
  </script>
 
  ...
 
  <span id="follow-placeholder"></span>
  <script type="text/javascript">
    twttr.anywhere(function (T) {
      T("#follow-placeholder").followButton('anywhere');
    });
  </script>
  </body>
</html>

@Anywhereの機能

ユーザーネームの自動リンク
ホバーカード
フォローボタン
ツイートボックス
ログイン機能

自動リンク

ページ内のTwitterのユーザーネームを、簡単にTwitter.comのプロフィールページへのリンクにすることができます。
Twitterのユーザー名は、"@"からはじまり、"_"など1-20文字の英数字で構成されます。

ユーザーネームを自動でリンクするには、linkifyUsersメソッドを使います。

twttr.anywhere(function (T) {
  T.linkifyUsers();
});

この方法だと、bodyタグ以下のすべてのユーザーネームをリンクしようとします。

リンクさせたい範囲を制限するには、CSS セレクタの要領で要素を指定します。
以下の例だと、linkify-this-contentというIDのついた要素内を対象に、リンクを行います。

twttr.anywhere(function (T) {
  T("#linkify-this-content").linkifyUsers();
});

linkifyUsersだけでなく他のAPIにも共通しますが、メソッドにはオプションを指定することができます。
例えば、作成したユーザーネームはtwitter-anywhere-userというクラスのついたaタグで囲まれます。
classNameをオブジェクトリテラルで渡すことにより、このクラス名を任意のものに変更することができます。
以下の例では、my-tweepというクラス名を付与しています。

twttr.anywhere(function (T) {
  T("#linkify-this-content").linkifyUsers({ className: 'my-tweep' });
});
// @<a class='twitter-anywhere-user'>hoge</a>ではなく、
// @<a class='my-tweep'>hoge</a>になる。

ホバーカード

ホバーカードは、Twitterのユーザー情報をツールチップの形式で表示することができます。
ホバーカード上では、フォローやアンフォローといった動作を行うこともできます。

一番簡単な使い方は以下。

twttr.anywhere(function (T) {
  T.hovercards();
});

デフォルトのhovercardsメソッドの挙動としては、bodyタグ以下に対して、上述のlinkifyUsersメソッドを内部で実行します。
その後で、デフォルトのクラス名のついたaタグで囲まれたユーザーネームをマウスオーバーすることで、ホバーカードを表示します。

ホバーカードのオプション

こちらも同じく、CSS セレクタの要領で適応範囲を制限できます。

twttr.anywhere(function (T) {
  T("#main-content").hovercards();
});

ユーザーネームをリンクにしない

linkfyプロパティをfalseにすることで、リンクの作成を回避することができます。

twttr.anywhere(function (T) {
  T("#main-content").hovercards({ linkify: false });
});

でも見た目がリンクじゃないとマウスオーバーなんてしないので、ユーザビリティ的には微妙かなぁ・・。

inferオプション

inferオプションを指定すると、hovercardsメソッドはlinkifyUsersメソッドを実行しません。
これは、何らかの事情で既にTwitterのユーザー名がリンクになってる場合に有効です。
@hogeを含むテキストがリンクになってる場合、そこにホバーカードを適応することができます。

twttr.anywhere(function (T) {
　T("#main-content a.my-tweep").hovercards({
　　infer: true
　});
});

usernameオプション

これは、例えば画像のtitleなどの要素がTwitterのユーザーネームを含んでいて、それに対してホバーカードを設定したい場合に使用します。
hovercardsメソッドにusernameプロパティを渡し、その値としてDOMから取得した要素を指定します。
注：inferオプションと同じく、これを使用した場合、hovercardsメソッドはlinkifyUsersメソッドを実行しません。

twttr.anywhere(function (T) {
　T("#section>img").hovercards({ // 画像にホバーカード
    username: function(node) {
      return node.alt; // altを対象にする
    }
  });
});

画像のaltに@hogeがある場合、画像マウスオーバーで、そのユーザー名をホバーカードすることができるんですね。
そこまでしてホバーカードすることってあるんかなぁ・・ともｗ
あ、画像ギャラリーとかには使えるかも？

上述の注通り、inferオプションもusernameオプションも、linkifyUsersメソッドは実行しません。
そのため、他の要素に対してはリンク作成をしたいという場合は、別途hovercardsメソッドを呼ぶことで解決できます。

twttr.anywhere(function (T) {
 
　T.hovercards();

　T("#main-content a.my-tweep").hovercards({
　　username: function(node) {
　　　return node.title;
    }
  });
});

ホバーカードを最初から展開する

デフォルトでは、ホバーカードに表示される情報は、ユーザー名とユーザーネーム、後はロケーションのみです。
「もっと読む」をクリックすることで、プロフィールやフォロー数などを確認することができます。
expandedプロパティをtrueにすることで、最初から全て展開した状態にすることもできます。

twttr.anywhere(function (T) {
　T("#main-content").hovercards({
　　expanded: true
　});
});

このホバーカード、かなりイケてると個人的には思うのです。
普通のREST APIでこれだけの情報を取得して表示するのは中々に手間なので・・。

フォローボタン

フォローボタンを設置することで、簡単にTwitterのユーザーをフォローさせることができます。
APIクライアントに対して、フォローボタンを表示させたい要素を渡し、ユーザーネームを指定してfollowButtonメソッドを呼び出すだけで使用できます。
下記の例では、follow-twitterapiというIDをもつspanタグに対して、フォローボタンを表示させています。

<span id="follow-twitterapi"></span>
<script type="text/javascript">

twttr.anywhere(function (T) {
　T('#follow-twitterapi').followButton("twitterapi");
});

</script>

この高機能なフォローボタンは、フォロー状況を随時表示します。
既にフォロー済の場合は「You're following @hoge」、鍵付きユーザーをフォローした場合は、「Follow pending for @hoge」、何らかのエラーでフォローに失敗した場合は、「Could not follow @hoge」と表示されます。

フォローボタン単体のAPIも公開されてるので、デザインも見慣れないコレを無理にこっちを使う必要はないかもですね。
参考：Follow Button | Twitter Developers

ツイートボックス

これを使えば、あなたのサイトやアプリから、直接ツイートを投稿することができます。ツイートボックスを表示したい要素をAPIクライアントに渡し、tweetBoxメソッドを実行します。
下記の例では、tboxというIDのついた要素にツイートボックスを表示します。

<div id="tbox"></div>
<script type="text/javascript">
 
  twttr.anywhere(function (T) {
    T("#tbox").tweetBox();
  });
 
</script>

オプション

ツイートボックスには、いくつかの設定をすることができます。
設定はすべてオブジェクトリテラルでtweetBoxメソッドに渡します。
下記の例では、width、height、初期表示文言をカスタマイズしています。

<div id="tbox"></div>
<script type="text/javascript">
 
  twttr.anywhere(function (T) {
 
    T("#tbox").tweetBox({
      height: 100,
      width: 400,
      defaultContent: "<YOUR DEFAULT TWEETBOX CONTENT HERE>"
    });
 
  });
 
</script>

下表は、オプションとして使用できるプロパティと値の一覧です。

ツイートボックスのオプション一覧

プロパティ	型	初期値	説明
counter	Boolean	true	文字数カウンターを設置します。
height	Number	65 (px)	ツイートボックスの高さを設定。
width	Number	515 (px)	ツイートボックスの幅を設定。
label	String	"What's happening?"	ツイートボックスの上部に表示する文字。
defaultContent	String	none	ツイートボックスに初期表示する文言。@mentionや#hashtagなどに便利。
onTweet	Function	none	ツイートボックスからの投稿完了イベント。イベントリスナーには、ツイート本文のみと、HTMLでのツイートが渡されます。
data	Object	none	投稿時のオプションを設定。REST/updateのオプションが指定できます。

REST/updateの詳細は、POST statuses/update | Twitter Developersを参照。
もちろんサーバーサイドで実装することもできますが、このお手軽さは魅力ですね！

ログイン機能

ホバーカードに表示されるプロフィールなど、@Anywhereの機能のいくつかはユーザーの認証なしで利用することができます。
しかしフォローボタンから他のユーザーをフォローする場合などは、ログイン認証を行う必要があります。
@Anywhereは、そのための機能も提供しています。

"Connect with Twitter"ボタンは、Twitterと安全に認証する方法を提供します。
これによって、ユーザーはAPIを呼び出す際に使用するアクセストークンを、あなたのアプリケーションに委ねることができます。

"Connect with Twitter"ボタンを表示するには、APIクライアントに対してボタンを表示させたい要素を渡し、connectButtonメソッドを呼び出します。

以下では、loginというIDののついたspanタグ内に、"Connect with Twitter"ボタンを表示しています。

<span id="login"></span>
<script type="text/javascript">
 
  twttr.anywhere(function (T) {
    T("#login").connectButton();
  });
 
</script>

"Connect with Twitter"ボタンは、そのサイズを指定することができます。
small、medium、large、xlargeから指定することができ、デフォルトではmediumです。

<span id="login"></span>
<script type="text/javascript">
 
  twttr.anywhere(function (T) {
    T("#login").connectButton({ size: "large" });
  });
 
</script>

オリジナルのログインボタン

もし標準の"Connect with Twitter"ボタンの見た目があなたのサイトにそぐわない場合は、独自のログインボタンを作成することもできます。
生成される全てのAPIクライアントはsigninメソッドを持っているので、自分でHTMLとCSSで作ったボタンに対して、クリックイベントでsigninメソッドをバンドルするだけです。

<button type="button" id="signin-btn">Connect with Twitter</button>
<script type="text/javascript">
 
  twttr.anywhere(function (T) { 
    document.getElementById("signin-btn").onclick = function () {
      T.signIn();
    };
 
  });
 
</script>

認証フロー

サイトを訪れたユーザーが、既にTwitterにログイン済の場合は、単純に「アプリとの連携を許可しますか？」というポップアップが表示されます。
もしログイン済でない場合は、ログインを促すポップアップを表示します。

ログイン状態を判断する

いくつかの方法で、ユーザーがあなたのアプリケーションを認証しているか・ログインしているかを判断することができます。

authCompleteイベントとsingOutイベント

これらのイベントによって、ユーザーがあなたのアプリケーションを認証しているか・ログインしているかを判断することができます。

connectButtonメソッドにauthCompleteイベントとsingOutイベントを引数として渡すことが可能です。
authCompleteに対しては、唯一の引数として「ログインしたユーザー」の情報が渡されます。

  twttr.anywhere(function (T) {
    T("#login").connectButton({
      authComplete: function(user) {
        // 認証後に発火
      },
      signOut: function() {
        // ログアウトしたら発火
      }
    });
  });

authCompleteイベントとsingOutイベントは、どちらもAPIクライアントから参照することができるので、独自の機能をバインドすることもできます。
以下に例を示します。

  twttr.anywhere(function (T) {
 
    T.bind("authComplete", function (e, user) {
      // authCompleteに機能を追加
    });
 
    T.bind("signOut", function (e) {
      // singOutに機能を追加
    });
 
  });

ログインユーザーの情報を使う

isConnectedメソッドは、ユーザーのログイン状態を判別するのに便利です。ログイン時に、currentUserというプロパティが設定され、ユーザーの情報を取得することができます。

以下の例では、jQueryを使ってログインしていれば名前とプロフィール画像を、ログインしてなければログインボタンを表示します。

<span id="twitter-connect-placeholder"></span>
<script type="text/javascript">
  twttr.anywhere(function (T) {
 
    var currentUser,
        screenName,
        profileImage,
        profileImageTag;
 
    if (T.isConnected()) {
      currentUser = T.currentUser;
      screenName = currentUser.data('screen_name');
      profileImage = currentUser.data('profile_image_url');
      profileImageTag = "<img src='" + profileImage + "'/>";
      $('#twitter-connect-placeholder').append("Logged in as " + profileImageTag + " " + screenName);
    } else {
      T("#twitter-connect-placeholder").connectButton();
    };
 
  });
</script>

一度ユーザーがアプリケーションを認証すると、twitter_anywhere_identityというログインしたユーザーのIDを識別するCookieを発行するようになります。
サーバーサイドでログインユーザーを管理する場合は、これを使うことができます。
Cookieのフォーマットは、user_id:signature となっています。
この情報を使って、本当にTwitterで認証されたかどうかをサーバーサイドで判断することをオススメします。
この情報を照合するには、user_idに取得したConsumer Secretを足して、SHA1 アルゴリズムでハッシュ化します。
この結果が、Cookie内のsignatureと一致すれば、照合できたことになります。

Digest::SHA1.hexdigest(user_id + consumer_secret)

ここでやっと、最初にメモしたConsumer Secretが登場します。
公式のサンプルはRubyしかないのですが、PHPでもなんでもOKです。
PHPでの認証部分は、後でまた記事にしようと思います。

ログアウト

ログイン機能を提供するのであれば、もちろんログアウト機能も提供すべきです。twttr.anywhere.signOutメソッドを使うことで、ユーザーをログアウトさせることができます。
以下はもっともシンプルなログアウトボタンの例です。

<button type="button" onclick="twttr.anywhere.signOut();">Sign out of Twitter</button>

その他にも、ユーザーのログイン状態から判断して、ログインボタンとログアウトボタンを出し分けることもできます。
以下にjQueryを使用した例を示します。

<span id="login-logout"></span>
<script type="text/javascript">
 
  jQuery(function () {
 
    twttr.anywhere(function (T) {
 
      if (T.isConnected()) {
 
        $("#login-logout").append('<button id="signout" type="button">Sign out of Twitter</button>');
 
        $("#signout").bind("click", function () {
          twttr.anywhere.signOut();
        });
 
      }
      else {
        T("#login-logout").connectButton();
      }
 
    });
 
  });
 
</script>

YUI3ライブラリでやる場合の例は以下です。

<span id="login-logout"></span>
<script type="text/javascript">
 
  YUI().use("node", function(Y) {
 
    Y.on("domready", function () {
 
      twttr.anywhere(function (T) {
 
        if (T.isConnected()) {
 
          Y.one("#login-logout").append('<button id="signout" type="button">Sign out of Twitter</button>');
 
          Y.one("#signout").on("click", function () {
            twttr.anywhere.signOut();
          });
 
        }
        else {
          T("#login-logout").connectButton();
        }
 
      });
 
    });
 
  });
</script>

currentUserの持つプロパティ

ログインしているユーザーの情報は、currentUserプロパティから取得することができます。
このユーザー情報のオブジェクトはdataメソッドを持っており、取得したい情報を指定してやることで、その情報を取得できます。
以下がその一覧です。

Name	Type
profile_background_color	String
description	String
profile_text_color	String
followers_count	Number
lang	String
time_zone	String
utc_offset	Number
friends_count	Number
profile_link_color	String
statuses_count	Number
created_at	String
following	Boolean
favourites_count	Number
profile_sidebar_fill_color	String
contributors_enabled	Boolean
notifications	Boolean
protected	Boolean
profile_image_url	String
geo_enabled	Boolean
profile_background_image_url	String
profile_sidebar_border_color	String
url	String
location	String
name	String
screen_name	String
id	Number
verified	Boolean
profile_background_tile	Boolean

ベストプラクティス

@Anywhereでは、OAuth 2.0 specificationにある"User-agent flow"に従って、ユーザー認証後はその認証を行ったページURLにリダイレクトするようになっています。
anywhere.jsのファイルを出来る限りソースの上部に記述することで、アクセストークン取得のフローをより迅速に行うことができます。

JavaScriptファイルをページ下部に記述することは、一般的にサイトのパフォーマンス向上の常套手段となっています。
しかし、@AnywhereのJsファイルに限っては、ページ上部に可能な限り配置するようにしてください。このJsファイルは3KBと軽量で、なおかつGzip圧縮され提供されます。その上、@Anywhereに関する機能は全て非同期に読み込まれ、サイトパフォーマンスにはほとんど影響しないからです。

@AnywhereのJsファイルをページ下部に記述した場合、いくつか知っておくべき点があります。
まず最初に、パフォーマンスへの影響が考えられます。
ポップアップでのTwitterのログイン認証から、認証元のページにリダイレクトしたとしても、@AnywhereのJsファイルが読み込まれるまで、ポップアップが消えることはありません。ポップアップが認証後すぐに閉じられないということは、言うまでもなくユーザービリティの低下につながります。

その他にも、GoogleAnalyticsなどの計測ツールが二重カウントするなど、誤った情報を提供することがあります。

独自のコールバックURLを使用する

もしページ上部に@AnywhereのJsファイルを記述できない理由がある場合は、特定のURLにリダイレクトさせることもできます。
これは空のページでも構いませんが、@AnywhereのJsファイルを読み込んでおり、かつ@Anywhereに登録しているURLと、ドメイン・サブドメイン共に一致している必要があります。

twttr.anywhere.config({ callbackURL: "http://www.yoursite.com/anywhere-complete" });
 
twttr.anywhere(function (T) {
  T.hovercards();
});

twttr.anywhere.configは、anywhere関数を実行する前に設定する必要があります。
そして、コールバックURLは@Anywhereに登録しているURLと、ドメイン・サブドメイン共に一致している必要があります。

新規ドメインを登録する

いくつかのサイト・ドメインでまとめて@Anywhereを使用したい場合もあるでしょう。
デフォルトでは、アプリケーションを登録した際のCallbackURLに記入したドメインでのみ動作するようになっています。
ドメインを追加するには、アプリケーションの登録ページへ行き、@Anywhere domainタブから設定します。
ドメインは全部で5つまで登録することができます。

セレクタについて

@Anywhereでは、Sizzleライブラリを使用しています。
SizzleはCSS2.1とCSS3セレクタをサポートしています。
詳しい情報は、Sizzle documentationを参照してください。

バージョン情報

現在、@Anywhereのバージョンは1です。以前のバージョンでは、一部サポートしていない・動作しない機能があります。

メジャーバージョンを指定することで、その時点での最新版を使用することができます。
例えば1と指定することで、現時点で最新の1.2.1を使用することができます。
バージョンについては、@AnywhereのJsファイル読み込み時にパラメータとして指定します。
マイナーバージョンを使用することも可能で、複数のバージョンを同時に利用することも可能です。

<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
    <title>Anywhere Sample</title>
    <script src="http://platform.twitter.com/anywhere.js?id=YOUR_API_KEY" type="text/javascript"></script>
  </head>
  <body>
 
  <script type="text/javascript">
 
    twttr.anywhere("1.2.1", function (T) {
      // Using version 1.2.1
    });
 
    twttr.anywhere("1.4", function (T) {
      // Using version 1.4
    });
 
  </script>
 
  </body>
</html>

最初の読み込みのところ、v=1ってのがいらなくなるんですね。

異なるウィンドウを指定する

メインのウィンドウとは別のウィンドウで、@Anywhereを使用したい場合もあると思います。
例えば、iframe内でも@Anywhereは利用することができます。
twttr.anywhereメソッドに対して、使用したいwindowを渡すことで、利用できます。

twttr.anywhere({ window: myFrame }, function (T) {
  // Your code here
});

サポートブラウザ

メジャーバージョン1では以下のブラウザをサポートしています。

いつの情報やねん！

おわりに

原文に忠実に訳したつもりではありますが、意訳も多々含んでます。
少しでも怪しいと思ったら、原文を確認することをオススメします。

その他関連する仕様としてみておくべきものを載せておきます。

仕様に関して

利用制限・リミットについて

参考：@anywhere rate limits | Twitter Developers

このリミットについてがなぜ公式のトップの見える範囲に載ってないのかは甚だ疑問ではあります。
@AnywhereはAPIを無制限に使いまくれる・・かのように思われがちですが、そんなはずはありません。
他のAPIと一緒で、リクエスト元のIPに対して、

認証前ユーザーだと150回/時
認証後だと350回/時

というれっきとしたリミットがあります。

フォローボタンなんかは一回生成する度に1回なので、ほとんど使い物になりません・・・