Twitter 新 API のドキュメント「Getting Started with @Anywhere」日本語訳
先日行われた Twitter の開発者向けイベント「Chirp」にて、 @Anywhere という新 API が公開されました。自分のサイトに、 JavaScript のみでユーザー情報の表示やつぶやきの投稿、ユーザー認証などの機能を実装できる、とても興味深い API です。
この @Anywhere は使い方も非常に手軽で、こちらのページでサイトを登録すれば、あとは「Getting Started with @Anywhere」にある JavaScript をページに挿入するだけで利用できます。しかし、当然ですが説明は英語ですので、日本人には少しとっつきづらい面もあります。こんな有用な API が日本で普及しないのは大きな損失、ということで前述のページを日本語に翻訳してみました。
勢いで翻訳したので表現はかなり適当ですが、まあ無いよりはましかと思います（笑）。 @Anywhere を利用する際は、ぜひご活用ください。
以降、「Getting Started with @Anywhere」の日本語訳です。
Twitter @Anywhere はあなたのサイトに Twitter のコミュニケーション・プラットフォームをもたらす簡易デプロイ・ソリューションです。フォローボタン、ホバーカード、リンクされた @username の追加、そして "Connect to Twitter" による緊密な統合が行えます。 @Anywhere はあなたのサイトのより積極的なユーザー・ベースを促進します。
開始
順を追って説明していきます。 @Anywhere を開始するには、まずクライアント・アプリケーションを Twitter に登録する必要があります。既存のアプリケーションを使用することもできますが、 @Anywhere のために新規作成することをお勧めします。正常に機能させるために、アプリケーションの callback URL 属性は @Anywhere を利用する Web アプリケーションのドメインとサブドメインの両方に一致しなくてはなりません。 API key は @Anywhere の consumer key と同じです。
@Anywhere の機能を利用するすべてのページに、 http://platform.twitter.com/anywhere.js のクエリーパラメータに API key (id=) と利用する @Anywhere バージョン (v=) を付加した Javascript リソースを読み込む SCRIPT タグを挿入してください。
<!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=YourAPIKey&v=1" type="text/javascript"></script>
</head>
<body>
...
</body>
</html>
現在、 @Anywhere はバージョン 1 をサポートしています。 @Anywhere のその後のバージョンは以前のバージョンとの後方互換性のない新機能や変更を含むかもしれません。
@Anywhere のバージョン 1 は Mozilla Firefox 3.x, Google Chrome, Apple, Safari 4, Opera 10, Internet Explorer versions 6, 7, 8 をサポートします。
@Anywhere Javascript をページに挿入したら、 body の onLoad ハンドラや HTML ページの最後で @Anywhere になにをしてほしいかを伝えます。ほとんどの場合、呼び出し形式はとても簡単です。
twttr.anywhere(callback, optionalWindowContext)
@Anywhere の初期化完了時に一回だけ呼ばれるコールバック・メソッドを指定して twttr.anywhere メソッド呼び出さなければなりません。このコールバックには唯一の引数 twitter が引き渡されます。 twitter は、あなたのサイトでの Twitter の機能を有効・無効にできるインターフェースです。このインターフェースは jQuery のセレクタ・エンジン（変更された Sizzle）と同じです。 ― 実際、 @Anywhere （および Twitter.com）は広範囲に jQuery を使用しています。
初期化処理の例
<script type="text/javascript">
twttr.anywhere(onAnywhereLoad);
function onAnywhereLoad(twitter) {
// configure the @Anywhere environment
};
</script>
異なる window コンテキストでの @Anywhere の使用
@Anywhere を別の window コンテキストで使用したいことがあるかもしれません。そのために、 window コンテキストを指定するための省略可能な 2 番目のパラメータを @Anywhere initializer に提供しています。
<script type="text/javascript">
twttr.anywhere(onAnywhereLoad, myIframe.contentWindow);
function onAnywhereLoad(twitter) {
// configure the @anywhere environment
};
</script>
これにより、後続の @Anywhere API のメソッド呼び出しは指定されたコンテキストを対象にします。
@Anywhere の機能
@username の自動リンク
ユーザーの自動リンク化は、 DOM を巡回して Twitter スクリーン名の自動リンクを試みます。 Twitter スクリーン名は、 '@' シンボルで始まり、 1〜20 文字の英数字かアンダースコア ("_") が続くものです。自動リンク化の処理は DOM 操作時に保守的なアプローチをとります。既存の DOM イベントハンドラやハイパーリンクは維持されます。
Twitter スクリーン名を自動リンク化するには、初期かコールバックの中で twitter.linkifyUsers() 関数を使用します :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter.linkifyUsers();
};
</script>
この方法による linkifyUsers 呼び出しは、そのページの <body> 内の Twitter ユーザーである可能性のあるものすべてをリンク化します。我々は A, SCRIPT, NOSCRIPT, OBJECT, IFRAME, TEXTAREA, INPUT, SELECT, BUTTON, STYLE, PRE, TITLE タグに囲まれたすべてのテキストは解析しないように注意します。
ページ上の全ユーザーの包括的なリンク化の処理はじゅうぶんに高速です — ページの構造やマッチするスクリーン名の数に依存しますが、平均で 150-200ms と仮定できます。もちろん、あなたがページ全体のリンク化を望まないなら、我々はいくつかの代替手段を提供します。およそすべての @Anywhere API 呼び出しは、省略可能な DOM セレクタを指定できます :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter("#linkify-this-content").linkifyUsers();
};
</script>
ご想像のとおり、これは DOM id 'linkify-this-content' を持つ要素の内容のみを解析するように linkifyUsers に伝えます。以前に言及したように、セレクタエンジンは内部で jQuery を使用しています。 DOM セレクタのドキュメントは api.jquery.com を参照してください。
［原文では自動リンクを使用した例が表示されますが、ここでは省略します m(_ _)m］
リンク化、および他のほとんどの API メソッドは、あなたのページとの連携方法を変更できるいくつかの追加オプションをとります。例えば、デフォルトではリンク化されたスクリーン名はマッチした名前をアンカー <a class='twitter-anywhere-user'></a> でラップします。 className という key/value ペアを指定することで、代わりの CSS クラスを指定できます。例えば、 CSS クラスを "my-tweep" に変更するには :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter("#linkify-this-content").linkifyUsers({
className: 'my-tweep'
});
};
</script>
さらに、 'success' コールバックをほとんどの API 操作に指定できます。特定の操作が完了したとき、 APIClient object （すべての API 呼び出しのプロキシであるオブジェクト）の参照を伴って、この success コールバックが呼び出されます。これにより、 API コールをエレガントに連続実行できます :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter.linkifyUsers({
success: function(twitter) {
// ...do other things with twitter...
}
});
};
</script>
ホバーカード
ホバーカードは Twitter.com で見ることができる機能で、そして今、 @Anywhere を通して開発者が利用可能になりました。ホバーカードは、特定の Twitter ユーザーのデータへのシングル・クリック・アクセスを提供する、文脈依存の小さなツールチップです。また、ホバーカードはその Twitter ユーザーに関するアクションを可能にします。フォローやフォロー解除、デバイス・アップデートのトグル、リツィート、返信設定がすべてホバーカード内からアクセス可能です。
［使用例は原文をご参照ください］
ユーザーの自動リンク化と同様、開発者がホバーカードを有効にするのに使えるデフォルト・メソッドがあります (twitter.hovercards()) :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter.hovercards();
};
</script>
注意点は、このデフォルトの hovercards メソッド呼び出しがあらかじめ暗黙的に linkifyUsers を document body 全体に対して呼び出すことです。次に、デフォルトのリンク化クラス名にマッチするすべてのアンカータグ（'''<a class='twitter-anywhere-user'></a>'''）のマウスオーバーで、ホバーカードが有効化されます。アクション・コントロールは操作ユーザーが現在 Twitter にログインしている場合のみ機能します。
また、ホバーカードは多様なオプションを受け付けます。まずはどの要素がホバーカードを表示するかを制御するセレクタです :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter("#main-content a.my-tweep").hovercards();
};
</script>
上記の例では、 DOM id 'main-content' を持つ要素の子孫で、且つクラス 'my-tweep' を持つアンカータグだけがマウスオーバーでホバーカードを表示します。デフォルトでは、特定の Twitter ユーザーに関するホバーカードを表示するとき、どのユーザーの情報を表示する必要があるかを決定するためにアンカータグのテキストを見ます。 Twitter.com 上では、これらのユーザーへのリンクは @<a ... >username</a> の形式です。
もし非標準のリンク・テキストやアバターにホバーカードを表示したいなら、他のオプションがいくつかあります :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter("#main-content a.my-tweep").hovercards({
infer: true
});
};
</script>
'infer' オプションはリンク・テキストがスクリーン名を含むときに便利です。これは <a ...>Follow @biz on Twitter!</a> のようなリンクに対して使用できます。
infer オプションは、潜在的な Twitter スクリーン名を抽出するために、リンクテキストに対して正規表現を適用します。我々はあなたが画像、ハイパーリンク以外の要素、または実際のスクリーン名をテキストに含まないリンクにホバーカードを表示したいかもしれないと予想します。その場合のために、我々はまた別のオプションを提供しています :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
// Get the username from the node via a custom function that you provide.
// For example, suppose that the title element of each anchor has
// the username.
twitter("#section>a").hovercards({
username: function(node) {
return node.title;
}
});
};
</script>
この例では、あなたのサイトのユーザーが上記のセレクタで指定された任意のリンク上にホバーしたとき、開発者に指定された暗黙的もしくは明示的なコールバックに生の DOM 要素が引き渡されます。次にあなたは、あなたが望む任意のロジック（走査、属性ルックアップ、操作）を自由に実行します — 最終的に、我々は単純にこのコールバックが Twitter ユーザーのスクリーン名を返すと仮定します。 'infer' もしくは 'username' オプションのいずれかを指定すると、デフォルトのリンク化は実行されないことに注意してください。もしリンクされていないスクリーン名のリンク化とホバーカードの追加に加えて他の要素へのホバーカードの追加も行いたいなら、 chaining によって実現できます :
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter.hovercards();
twitter("#main-content a.my-tweep").hovercards({
username: function(node) {
// ...
return node.title;
}
});
};
</script>
フォローボタン
アプリケーションにフォローボタンを追加するのは簡単です。フォローボタンを配置したい既存の DOM 要素とフォロー操作のターゲットにしたいスクリーン名を与えて、カレント twitter オブジェクトの followButton メソッドを使用します。例えば、 DOM 要素 follow-twitterapi を @twitterapi をフォローするボタンにしたいなら :
<div id="follow-twitterapi"></div>
<script type="text/javascript">
function onAnywhereLoad(twitter) {
// this is the callback function you specified in your initializer
twitter('#follow-twitterapi').followButton("twitterapi");
};
</script>
［使用例は原文をご参照ください］
現在のユーザーが既にそのメンバーをフォローしているかどうかを反映するので、 Twitter @anywhere フォローボタンはスマートです。
Tweet Box
あなたのアプリケーションから直接つぶやきを投稿させたいですか？ 特定のテキスト（@mention や #hashtag のような）や特定のアクションの名前（"What's happening?" のような）とともにつぶやきを事前配置できる構成可能な @Anywhere モジュール、 Tweet Box を使ってください。また、つぶやきの投稿が成功したときに呼び出される Javascript コールバックも指定できます — つぶやきをデータベースに保存する良い機会です。
| Parameter | Expected Values | Default | Description |
|---|---|---|---|
| counter | boolean | true | Display a counter in the Tweet Box for counting characters |
| height | integer | 515 (px) | The height of the Tweet Box, specified as an integer representing a pixel value |
| width | integer | 65 (px) | The width of the Tweet Box, specified as an integer representing a pixel value |
| label | string | "What's happening?" | The text above the Tweet Box, a call to action. |
| defaultContent | string | none | Pre-populated text in the Tweet Box. Useful for an @mention, a #hashtag, a link, etc. |
| onTweet | function | none | Specify a callback that takes two arguments: a plaintext tweet and an HTML tweet |
これは Tweet Box のわずかな例です :
<span id="placeholder"></span>
<script type="text/javascript">
twttr.anywhere("1", function (twitter) {
// Appends a TweetBox to the specified element.
// The TweetBox will be rendered with the following
// default options:
// - Rendered with a counter
// - Dimensions: width: 65px, height: 515px
// - Labeled with "What's happening?"
twitter("#placeholder").tweetBox();
// Any of the default options can be modified by passing an
// object literal to the tweetBox method.
twitter("#placeholder").tweetBox({
counter: false,
height: 100,
width: 400,
label: "Tweet about this article:"
});
// Additionally, you can render the TweetBox with default text:
twitter("#placeholder").tweetBox({
defaultContent: "<YOUR DEFAULT TWEETBOX CONTENT HERE>"
});
// You can also listen for when a Tweet is sent by providing
// a listener for the tweet event:
twitter("#placeholder").tweetBox({
onTweet: function (tweet, renderedTweet) {
tweet // the tweet text
renderedTweet // the tweet rendered in HTML
}
});
});
</script>
これは Tweet Box がどのように表示されるかの例です。
［使用例は原文をご参照ください］
ユーザーログイン & サインアップ
Connect with Twitter はユーザー承認なしではできない緊密な統合を可能にします。これらの機能は、 Twitter でユーザーを安全に認証する方法と API コールに使うアクセス・トークンをアプリケーションに引き渡す方法を提供します。
<div id="twitter-connect-placeholder"></div>
<script type="text/javascript">
var anywhereApiKey = "abcdefghi-123";
twttr.anywhere(anywhereApiKey, "1.0.0", onAnywhereLoad);
function onAnywhereLoad(twitter) {
// Simplest use case: Append a connect button to the specified DOM
// element.
twitter("#twitter-connect-placeholder").connectButton();
// Connect buttons have a range of sizes to choose from:
// small, medium, large, xlarge. "medium" is the default size.
// You can specify the size as follows:
twitter("#twitter-connect-placeholder").connectButton({ size: "large" });
};
</script>
Twitter への接続フロー
クリックすると、 Twitter の安全な @Anywhere 認証ページがポップアップし、ユーザーにあなたのサイトのアクセスを承認するかどうかを尋ねます。
［使用例は原文をご参照ください］
カレント・ユーザーの利用
twitter.isConnected 関数は boolean を返します。この関数は Twitter との接続状態を表示するのに使えます。
加えて、コールバック関数を唯一の引数にとる twitter.User.current を呼び出すことで、カレント・ユーザー・オブジェクトを取得できます。このコールバックはカレント・ユーザー・オブジェクト（アクセスしたいデータを識別する文字列を引数にとる data メソッドに応答する）と共に呼び出されます。アクセスできるフィールドには、 screen_name と profile_image_url が含まれます。提供されるデータに関する完全なリストはもうすぐ利用可能になるでしょう。
※ 上の説明はコード例と明らかに矛盾していますが、原文どおりに訳したつもりです。もし誤訳でしたら、申し訳ありません。
これは、もしユーザーが既に認証されていたら、そのスクリーン名とプロフィール画像を表示し、そうでなければ Connect with Twitter ボタンを表示する例です。
<div id="twitter-connect-placeholder"></div>
<script type="text/javascript">
var anywhereApiKey = "abcdefghi-123";
twttr.anywhere(anywhereApiKey, "1.0.0", onAnywhereLoad);
function onAnywhereLoad(twitter) {
# Conditionally display the Connect Button based on current logged in state:
if (twitter.isConnected) {
currentUser = twitter.User.current;
screenName = currentUser.data('screen_name');
profileImage = currentUser.data('profile_image_url');
profileImageTag = "<img src='" + profileImage + "'/>";
$('#twitter-connect-placeholder').innerHTML = "Logged in as " + profileImageTag + " " + screenName;
} else {
twitter("#twitter-connect-placeholder").connectButton();
};
};
</script>
カレント・ユーザーのログアウト
@Anywhere コールバック内部では、あなたのサイトから現在のユーザーをログアウトさせるために twttr.anywhere.signOut() を実行できます。あなたが提供したリンクにアタッチされた関数としてログアウトを使用するのが最適です。例えば :
<a href="#" onClick="twttr.anywhere.signOut();">Sign out of Twitter</a>
接続状態を監視する他の方法
また、 connectButton を呼び出すとき、 authoComplete と signOut 属性を定義してコールバック関数を指定できます:
twitter.connectButton({
authComplete: function(loggedInUser) {
// triggered when auth completed successfully
},
signOut: function() {
// triggered when user logs out
}
});
And that's @Anywhere!
来たる数週間、より多くのドキュメンテーションや機能を楽しみにしてください!
詳しくはこちらの記事をどうぞ！
この記事にコメントする