App Linksの技術文書を和訳してみました

Written on May 12, 2014. Posted in Web Technologies

4月20日に行われたFacebookの開発者向けイベント「F8」にて、App Linksという新しい仕様が発表されました。これは、今までのWebでのページ間リンクのように、スマートフォンアプリ間の「ディープリンク」を可能にするための標準的な手続きになるべく発表されたものです。具体的な仕様について、さっそく和訳をしてみました。これだけ読んでもちょっと理解するのが難しいのですが、参考になると幸いです。

原文は、 http://applinks.org/documentation/です。

App Linksの公開

App Linkメタデータの公開は、あなたのコンテンツ内にタグを数行追加するだけという単純さです。あなたのコンテンツにリンクするアプリは、あなたのアプリ内にディープリンクすることや、アプリをダウンロードするためにアプリストアへユーザを誘導すること、またはそのコンテンツを閲覧するためにWebへ直接彼らを誘導する際に、このメタデータを利用することが可能です。これは、開発者に対して、それらのコンテンツにリンクする際の彼らのユーザのための最も良いと考えられる体験を提供します。

App Linksは、以下のレジストリ内で定義されるタグを使って指定されます。相手にディープリンクするためにそのアプリに十分な内容を提供するために、対象とするプラットフォームごとに異なるメタデータのセットが要求されます。

App Linkメタデータを提供する単純なWebページは、このようになるでしょう:

File: documentation.html

<html>
<head>
    <meta property="al:ios:url" content="applinks://docs" />
    <meta property="al:ios:app_store_id" content="12345" />
    <meta property="al:ios:app_name" content="App Links" />
    <meta property="al:android:url" content="applinks://docs" />
    <meta property="al:android:app_name" content="App Links" />
    <meta property="al:android:package" content="org.applinks" />
    <meta property="al:web:url"
          content="http://applinks.org/documentation" />
</head>
<body>
Hello, world!
</body>
</html>

プラットフォームメタデータスキーマ

以下のタグは、あなたのサイトでApp Linkメタデータを定義するために使用されます。各デバイスタイプは、複数の値を収容するために複数回指定可能であり、ナビゲートする際の検索のためのアプリのフォールバックリストを提供することができます（例えば、アプリに無料および有料のバージョンがある場合や、複数のバージョンが存在し、それぞれ異なるディープリンクをハンドリングしたい場合）。

また、あなたのアプリは、もしそのアプリがインストールされていない場合にWebブラウザ内で読み込まれる単一のフォールバックURLを定義することができるでしょう。もしあなたのアプリが等価のWebコンテンツを持たない場合は、あなたのコンテンツをWebブラウザ内で表示するフォールバックを試みるべきではないことを他のアプリに指示するために、al:web:should_fallbackにfalseを指定することができるでしょう。

Device Type: iOS

プロパティ

コンテンツの例

説明

必須

al:ios:url

applinks://docs

iOSアプリのカスタムスキーム。

al:ios:app_store_id

12345

AppStoreのためのアプリID。

al:ios:app_name

App Links

(表示に適した)アプリの名前。

Device Type: iPhone

プロパティ

コンテンツの例

説明

必須

al:iphone:url

applinks://docs

iPhoneアプリのカスタムスキーム。

al:iphone:app_store_id

12345

AppStoreのためのアプリID。

al:iphone:app_name

App Links

(表示に適した)アプリの名前。

Device Type: iPad

プロパティ

コンテンツの例

説明

必須

al:ipad:url

applinks://docs

iPadアプリのカスタムスキーム。

al:ipad:app_store_id

12345

AppStoreのためのアプリID。

al:ipad:app_name

App Links

(表示に適した)アプリの名前。

Device Type: Android

プロパティ

コンテンツの例

説明

必須

al:android:url

applinks://docs

Androidアプリのカスタムスキーム。

al:android:package

org.applinks

インテント生成のための完全修飾されたパッケージ名。

al:android:class

org.applinks.DocActivity

インテント生成のための完全修飾されたアクティビティクラス名。

al:android:app_name

App Links

(表示に適した)アプリの名前。

Device Type: Windows Phone

プロパティ

コンテンツの例

説明

必須

al:windows_phone:url

applinks://docs

Windows Phoneアプリのカスタムスキーム。

al:windows_phone:app_id

a14e93aa-27c7-df11-a844-00237de2db9f

App storeのためのアプリID（GUID）。

al:windows_phone:app_name

App Links

(表示に適した)アプリの名前。

Webフォールバック

プロパティ

コンテンツの例

説明

必須

al:web:url

http://applinks.org/documentation

Web URL; 初期値は、このタグを含むコンテンツのURL。

al:web:should_fallback

false

Web URLがフォールバックとして使われるべきかどうかの指示; 初期値はtrue。

App LinkメタデータのURLのクロールの際、開発者は Prefer-Html-Meta-Tagsヘッダにプレフィックス値の1つとして alを持つリクエストを送るべきです。あなたのサーバは、上記のタグのみが書かれたHTMLを含むレスポンスに限定することを選択することができるでしょうし、与えられた場所のレスポンスタイプが text/htmlではない別の何かになる時でさえ、それらのタグを返すためのシグナルとしてこれを使うことも可能です。

Prefer-Html-Meta-Tags: al

App Linkメタデータの例

App Linkメタデータ指定時の共通的な場面でのいくつかの例は、以下になります。

iOSおよびWebでのみ利用可能なアプリ:

<html>
<head>
    <meta property="al:ios:url" content="applinks://docs" />
    <meta property="al:ios:app_store_id" content="12345" />
    <meta property="al:ios:app_name" content="App Links" />
    <!-- 他のヘッダ -->
</head>
<!-- 他のHTMLコンテンツ -->
</html>

デバイス上で利用可能な最新のバージョンを使うことを試みるはずのリンクを辿るiOSの複数バージョンを持つアプリ:

<html>
<head>
    <meta property="al:ios" />
    <meta property="al:ios:url" content="applinks_v2://docs" />
    <meta property="al:ios:app_store_id" content="12345" />
    <meta property="al:ios:app_name" content="App Links" />
    <meta property="al:ios" />
    <meta property="al:ios:url" content="applinks_v1://browse" />
    <meta property="al:ios:app_name" content="App Links" />
    <!-- 他のヘッダ -->
</head>
<!-- 他のHTMLコンテンツ -->
</html>

iPadとiPhoneバージョンを持つアプリ:

<html>
<head>
    <meta property="al:iphone:url" content="applinks://docs" />
    <meta property="al:iphone:app_store_id" content="12345" />
    <meta property="al:iphone:app_name" content="App Links" />
    <meta property="al:ipad:url" content="applinks://docs" />
    <meta property="al:ipad:app_store_id" content="67890" />
    <meta property="al:ipad:app_name" content="App Links" />
    <!-- 他のヘッダ -->
</head>
<!-- 他のHTMLコンテンツ -->
</html>

Webコンテンツを持たないが、iOSとAndroidを持つアプリ:

<html>
<head>
    <meta property="al:android:package" content="org.applinks" />
    <meta property="al:android:url" content="applinks://docs" />
    <meta property="al:android:app_name" content="App Links" />
    <meta property="al:ios:url" content="applinks://docs" />
    <meta property="al:ios:app_store_id" content="12345" />
    <meta property="al:ios:app_name" content="App Links" />
    <meta property="al:web:should_redirect" content="false" />
    <!-- 他のヘッダ -->
</head>
<!-- 他のHTMLコンテンツ -->
</html>

別のURLで参照可能なWebコンテンツを持つアプリへの共有リンク:

<html>
<head>
    <meta property="al:android:package" content="org.applinks" />
    <meta property="al:android:url" content="applinks://docs" />
    <meta property="al:android:app_name" content="App Links" />
    <meta property="al:ios:url" content="applinks://docs" />
    <meta property="al:ios:app_store_id" content="12345" />
    <meta property="al:ios:app_name" content="App Links" />
    <meta property="al:web:url"
          content="http://www.example.com/applinks_docs" />
    <!-- 他のヘッダ -->
</head>
<!-- 他のHTMLコンテンツ -->
</html>

App Linkナビゲーションプロトコル

App Linkメタデータを含む対象のURLへの遷移は、2つのキーコンポーネントを持つ共通のプロトコルに従います:

以下のプラットフォーム固有の各セクションにて詳細が説明された、プラットフォームごとのディープリンク（例. iOS, WIndows Phone, Web, AndroidのインテントのURL）。
ナビゲーションのための内容を含むal_applink_dataオブジェクト。

al_applink_dataは、JSONオブジェクトで表現可能な任意の種類の情報を保持できるメタデータコンテナを意味します。al_applink_dataのトップレベルプロパティは、このプロトコルを使ったURLへの遷移の動きに関係するルーティング情報を含むことになります。

下のテーブルは、このプロトコルによって定義されるal_applink_dataのプロパティの一覧ですが、他の拡張プロトコルによって、追加のプロパティが定義されることもあるでしょう。

プロパティ

コンテンツの例

説明

必須

target_url

http://applinks.org/documentation

遷移先となるWeb URLを含む文字列。これは、任意のコンテンツを表現するhttpまたはhttpsのURLです。

extras

{“myapp_token”: “t0kEn”}

遷移するアプリの情報を含むオブジェクト。

version

1.0

プロトコルのバージョンを含む文字列 - 現在”1.0”であり、これが初期値です。

user_agent

Bolts Android 1.0

遷移を行う遷移処理のコードのライブラリの識別子を含む文字列。

例えば、http://example.com/docsに遷移するal_applink_dataは、以下のようになるでしょう:

{
  "target_url": "http://example.com/docs",
  "extras": {
    "myapp_token": "t0kEn"
  },
  "user_agent": "Bolts iOS 1.1",
  "version": "1.0"
}

iOSでの遷移

iOSでのディープリンクは、オペレーティングシステムがそのアプリを起動するであろうURLスキーム（例. myapp:// や example:// - 私たちは、他のアプリとの競合を防ぐため、アプリはユニークなURLスキームを選択することを強く望みます）を各アプリが登録し定義することができるので、URLベースです。iOS上でのApp Link遷移の実行は、上記で定義されたal_applink_dataを持つアプリによって定義されるプレフィックスを組み合わせたURLの構築を必要とします。

iOSでの対象のURLへの遷移のために、以下を行います:

対象のURLのApp Linkメタデータを集めます。
あなたのデバイス向け（言い換えれば、iPhoneやiPod touch向けのiphone、iPad向けのipad）のメタデータ内のURLを開くことが可能な、そのメタデータ内で定義される最初のApp Link対象を検索します。
もし対象が見つからなかった場合、ios向けのメタデータ内のURLを開くことが可能なそのメタデータ内で定義される最初のApp Linkターゲットを検索します。
このデバイス上で開くことが可能な対象が見つからず、al:web:should_fallbackがfalseの場合は、遷移は失敗します。そうではない場合は、ターゲットとしてal:web:url値（もしnoneが指定される場合は、オリジナルのターゲットURL）を選択します。
遷移のためのal_applink_dataを構築し、JSON文字列としてそれをエンコードして、その文字列をURLエンコードします。そして、al_applink_dataという名前のクエリパラメータとしてそれを追加します。
構築されたURLを開きます。

例えば、もし http://example.com/applinks が以下のマークアップを含んでいた場合:

<html>
<head>
    <meta property="al:ios:url" content="example://applinks" />
    <meta property="al:ios:app_store_id" content="12345" />
    <meta property="al:ios:app_name" content="Example App" />
    <!-- 他のヘッダ -->
</head>
<!-- 他のHTMLコンテンツ -->
</html>

遷移するアプリがインストールされている場合は、以下のURLが開かれるでしょう:

example://applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20iOS%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

もしくは、そのアプリがインストールされていなかった場合は、以下のURLとなるでしょう。

http://example.com/applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20iOS%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

標準のal_applink_data属性に加えて、私達はiOS遷移のための以下の属性を定義しました:

プロパティ

コンテンツの例

説明

必須

referer_app_link

{ “target_url”: “http://example.com/docs”, “url”: “example://docs”, “app_name”: “Example App” }

対象URLだけでなく、この遷移のためのRefererを特定するために利用可能なiOSアプリリンクメタデータの一部分（メタデータレジストリ内で定義される）も含むJSONオブジェクト。これは、iOSがビルトインで戻るボタンを持たないので、遷移アプリにリンクバックを提供するためにアプリが受け取ることを可能にします。

Androidでの遷移

Androidのディープリンクは、オペレーティングシステムがアプリを起動するためのアクティビティ及びインテントフィルタを書くアプリが登録し定義することができるので、インテントベースです。Android上のApp Link遷移の実行は、インテント拡張内にal_applink_dataを含むインテントの構築が必要です。

Androidでの対象のURLへの遷移のために、以下を行います:

対象のURLへのApp Linkメタデータを収集します。
開くことが可能なAndroid向けのメタデータ内で定義された最初のApp Linkターゲットを探します。これを決定するために、指定されたクラスとパッケージを持つVIEWインテントを構築します。もしurlが指定される場合、インテントにデータとしてこれをセットします。そうでない場合、インテントにデータとしてターゲットURLをセットします。最後に、PackageManager.resolveActivity()を呼び出して何らかのResultInfoが返されるかどうかを確認することで、インテントが機能するかどうかをチェックします。
もしこのデバイスで開くことが可能な対象が見つからず、al:web:should_fallbackがfalseだった場合、遷移は失敗します。そうでない場合は、そのデバイスのデフォルトWebブラウザを起動するインテントを構築するためのal:web:url値（noneが指定されていた場合は、オリジナルのターゲットURL）を使用します。このURLに、JSON文字列としてエンコードされ、更にURLエンコードされた値を、al_applink_fdataという名前のクエリパラメータとしてあなたは追加すべきです。
もし適したターゲットや関連するインテントが見つかった場合、バンドル（値としてネストされたバンドル、文字列、値の配列を使用して）として遷移のためのal_applink_dataを構築し、al_applink_dataという名前の拡張としてインテントにそれを追加します。
構築されたインテントのアクティビティを開始します。

例えば、もし http://example.com/applinks が以下のマークアップを含む場合:

<html>
<head>
    <meta property="al:android:url" content="example://applinks" />
    <meta property="al:android:package" content="com.example" />
    <meta property="al:android:app_name" content="Example App" />
    <!-- 他のヘッダ -->
</head>
<!-- 他のHTMLコンテンツ -->
</html>

遷移するアプリがインストールされていた場合は、以下のインテントが開始されるでしょう:

action: android.intent.action.VIEW
data: example://applinks
package: com.example
extras:
  al_applink_data:
    target_url: "http://example.com/applinks"
    user_agent: "Bolts Android 1.0"
    version: "1.0"
    extras:
      myapp_token: "t0kEn"

もしくは、そのアプリがインストールされていなかった場合は、以下のインテントが開始されるでしょう:

action: android.intent.action.VIEW
data: http://example.com/applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20Android%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

Windows Phoneでの遷移

Windows Phoneでのディープリンクでは、オペレーティングシステムがアプリを起動するURLスキーム（例: myapp://やexample:// - 他のアプリと競合を避けるためにユニークなURLスキームを我々は強く推奨します）を各アプリが登録し定義することになるので、URLベースになります。Windows PhoneでのApp Link遷移の実行は、上記で定義されたal_applink_dataを持つアプリによって定義されたプリフィックスを組み合わせたURLを構築する必要があります。

Windows Phoneで対象のURLに遷移するためには、以下のことを行います:

対象のURLのためのApp Linkメタデータを収集します。
windows_phoneのメタデータ内で定義された各App Link対象を順に取得し、JSON文字列としてエンコードされ、更にURLエンコードされたこの遷移のためのal_applink_dataを含むal_applink_dataという名前のクエリパラメータを追加したURLを構築します。起動が成功するまで、そのURLの起動を試みます。
もしこのデバイス上で起動の試みが成功せず、al:web:should_fallbackがfalseだった場合は、遷移は失敗します。そうではない場合、al:web:url（noneが指定された場合は、オリジナルの対象URL）の値が使われ、上記のal_applink_dataが追加され、そしてこのURLの起動が試みられます。

例えば、もし http://example.com/applinks が以下のマークアップを含む場合:

example://applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20Windows%20Phone%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

もしくは、もしアプリがインストールされていなかった場合は、以下のURLになります。

http://example.com/applinks?al_applink_data=%7B%22user_agent%22%3A%22Bolts%20Windows%20Phone%201.0.0%22%2C%22target_url%22%3A%22http%3A%5C%2F%5C%2Fexample.com%5C%2Fapplinks%22%2C%22extras%22%3A%7B%22myapp_token%22%3A%22t0kEn%22%7D%7D

UXガイドライン/レコメンデーション

App Linksは、あなたのユーザにコンテンツが閲覧される際に彼らのデバイス向けに最適化された良い体験を提供することを可能にします。あなたは、あなたのアプリのためのApp Linkメタデータを持つリンクの表示を最適化するべきです。あなたは、このアプリがインストールされていない時に、ネイティブアプリストアにユーザを連れて行くことや、与えられたリンクのためのApp Linkメタデータをベースにしたアプリケーションの名前を表示することを選択可能です。

一般にWebでリンクに遷移するときのように、ユーザが遷移後に、遷移前のアプリに戻るための能力をそのユーザに与えたほうが便利です。AndroidやWindows Phoneなどのいくつかのプラットフォームでは、この機能を満たすためのバックボタンの概念がビルトインされています。

しかしながら、iOSのようないくつかのプラットフォームでは、バックボタンはありません。”iOSでの遷移”で話した通り、あるアプリが別のアプリに遷移する際、そのユーザにバックボタンを提供することを起動されたアプリができようにするための十分な情報を持つreferer_app_linkを提供できるでしょう。私達は、App Link遷移の受信者が、起動遷移がreferer_app_linkメタデータを持っていた場合に、以下の画像のような標準の”タップして戻る”UIを表示することを推奨します。

[img]

Bolts for iOSは、BFAppLinkReturnToRefererControllerクラスで発見可能な、このUIの参照実装を提供しています。この実装は、適したタイミングで”タップして戻る”UIを表示あるいは非表示することを処理し、タップをハンドルして前のアプリケーションへ戻る遷移を行う処理を扱います。

実装

開発者は、上記の説明に基づいて、彼ら自身で各プラットフォームのためのApp Linksプロトコルの実装を選択することができるでしょう。代わりに、開発者はApp Link遷移を適切に実行し、起動されたことを扱い、そしてApp Linkメタデータを公開することを助けるライブラリを使用することも選択可能です。

あなたは、App Link遷移での起動を受け取ったり遷移したりするために、以下の実装を使うことができるでしょう:

Bolts for iOS - iOSアプリのためのオープンソース参照実装。
Bolts for Android - Androidアプリのためのオープンソース参照実装。

以下のツールは、App Linkメタデータのコンテンツを公開することを助けてくれます。

Parse App Links Cloud Code Module - App Linkメタデータを持つWebコンテンツの公開を単純な方法で提供します。
Facebook App Links Hosting API - Facebookモバイル・アプリが、Webコンテンツの作成や修正なしにApp Linkメタデータを公開することが可能になるシンプルなエンドポイントです。

いくつかのプロバイダは、HTMLをあなた自身でスクレイピングおよびパースすることよりも、あなたのアプリで利用することを選択可能なApp Linkメタデータのハイパフォーマンスなインデックスへのアクセスも提供することができるでしょう: