Hatena::Grouphatenadeveloper

iPhone向けAPI - はてなブックマーク外部連携API

ja/iphone/apis/bookmark

iPhone向けAPI - はてなブックマーク外部連携API

本ドキュメントは、はてなブックマークiPhoneアプリケーションにおける、コメント画面及びブックマーク画面を呼び出す外部連携仕様について解説するものです。

はてなブックマークiPhoneアプリケーション外部連携APIとは

はてなブックマークiPhoneアプリケーション外部連携APIは、はてなブックマークiPhoneアプリケーションバージョン2.1以上において、外部のiPhoneアプリケーションから、はてなブックマークiPhoneアプリケーションのコメント閲覧画面と、ブックマーク追加画面を呼び出すことができるAPIです。

このAPIを使用することにより、外部アプリケーションからはてなブックマークにブックマークを追加する機能を簡単に付加することができます。

API仕様

外部連携にはスキーマ連携と呼ばれる仕組みを利用します。具体的にはhatenabookmark:/で始まるURLを呼び出すことで、アプリケーションを起動します。仕様は以下のとおりです。

コメント追加画面

APIへのリクエストサンプルを示します。

hatenabookmark:/entry?url=http%3A%2F%2Fb.hatena.ne.jp%2Fguide%2Fiphone_app2

hatenabookmark:をスキーマとし、エンドポイント/entryにアクセスします。パラメータとして必ずurlをとります。

パラメータの詳細

url
  • (必須)コメントを表示したいWebページのURL
  • URIエンコード済みのものを渡す。
  • 例: http%3A%2F%2Fb.hatena.ne.jp%2Fguide%2Fiphone_app2
title
  • (任意)urlパラメーターで指定されたWebページのタイトル
  • URIエンコード済みのものを渡す。
  • 指定されていなければブックマークアプリが独自に取得します。この場合、アプリに遷移してから非同期取得するため、タイトルの表示は遅くなります。
  • 例: %E3%81%AF%E3%81%A6%E3%81%AA%E3%83%96%E3%83%83%E3%82%AF%E3%83%9E%E3%83%BC%E3%82%AF%E5%85%AC%E5%BC%8FiPhone%E3%82%A2%E3%83%97%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3
backurl
  • (任意)戻るボタンの飛び先URL。呼び出し元アプリのスキーマを使ったURLを指定することを想定しています。
  • URIエンコード済みのものを渡す。
  • 指定されない場合は呼び出し元アプリに戻るボタンは表示されず、はてなブックマークアプリへ戻るボタンが表示されます。
  • 例: samplebrowser%3A%2top
backtitle
  • (任意)戻るボタンのタイトル
  • URIエンコード済みのものを渡す。
  • 指定された場合、「backtitleに戻る」(backtitleは指定した文字列)というタイトルが表示される
  • backurlが指定されていて、かつこのパラメーターが指定されないと、ボタンのタイトルは「戻る」となります。
  • 例: %E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB%E3%83%96%E3%83%A9%E3%82%A6%E3%82%B6

追加・編集画面

リクエストサンプルを示します。

hatenabookmark:/entry/add?url=http%3A%2F%2Fb.hatena.ne.jp%2Fguide%2Fiphone_app2

hatenabookmark:をスキーマとし、エンドポイント/entry/addにアクセスします。パラメータとして必ずurlをとります。

パラメータの詳細

url
  • (必須)コメントページものと同様です。
title
  • (任意)コメントページものと同様です。
backurl
  • (任意)コメントページものと同様です。
backtitle
  • (任意)コメントページものと同様です。

実装方法

以下、具体的な実装方法についてサンプルを用いながら解説します。

アプリを呼び出す際には以下のようにURLを組み立て、openURL:メソッドで起動します。URLのクエリパラメーターはすべてURLエンコードしてください。

NSURL *appURL = [NSURL URLWithString:
                  [NSString stringWithFormat:@"hatenabookmark:/entry?url=%@&backurl=%@&backtitle=%@",
                      [[URL absoluteString] stringByURLEncoding:NSUTF8StringEncoding],
                      [@"hatenabookmarksample:/" stringByURLEncoding:NSUTF8StringEncoding],
                      [@"はてなブックマークサンプル" stringByURLEncoding:NSUTF8StringEncoding]]];
if ([[UIApplication sharedApplication] canOpenURL:appURL]) {
    [[UIApplication sharedApplication] openURL:appURL];
}

また、ブックマーク追加後に呼び出し元アプリに戻す場合には、以下のようにInfo.plistに独自URLスキーマを定義し、はてなブックマークアプリケーションを呼び出す際にbackurlを指定してください。

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.hatena.bookmark.sample</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>hatenabookmarksample</string>
        </array>
    </dict>
</array>

Info.plistはXCodeから編集することもできます。

f:id:ninjinkun:20110405190236p:image

また、戻る際に特定の画面を指定したい場合はAppDelegateのapplication:handleOpenURL:メソッドにURLをハンドリングする処理を追加します。

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)URL {   
    if ([[URL path] isEqualToString:@"/sample"]) {
       SampleViewController *viewController =  [[[SampleViewController alloc] init] autorelease];
       [self.navigationController presentModalViewController:navController animated:NO];       
    }
    return NO;
}

サンプルプロジェクト

以下のURLにサンプルプロジェクトがあります。実装の参考にしてみてください。

https://github.com/hatena/iphone-hatena-bookmark-sample

ブックマークレット

はてなブックマークアプリを呼び出すブックマークレットのコードを以下に示します。実装の参考にしてみてください。

コメントを見る

(function() {var url = location.href;var title = document.title;location.href="hatenabookmark:/entry?url="+encodeURIComponent(url)+"&title="+encodeURIComponent(title)+"&backurl="+encodeURIComponent(url) + "&backtitle="+encodeURIComponent("Safari") ;
})()

ブックマークする

(function() {var url = location.href;var title = document.title;location.href="hatenabookmark:/entry/add?url="+encodeURIComponent(url)+"&title="+encodeURIComponent(title)+"&backurl="+encodeURIComponent(url)+"&backtitle="+encodeURIComponent("Safari") ;
})()

変更履歴

  • 2011年4月26日リリース