MAUIでディープリンク (App Links / Universal Links) を設定する方法をまとめました。 Webサイトは GitHub Pages + Jekyll でホスティングします。
- Apple Developer Console の設定
- GitHub Pages + Jekyll の設定
- MAUI アプリの設定
- 動作確認
Apple Developer Console の設定
iOS では Universal Links の設定のために Apple Developer Console での設定が必要です。Android は特に必要ありません。 Xcodeを使った開発においては、Xcodeから直接設定を行うことができますが、MAUIではマニュアルで設定する必要があります。
- Capability の追加:
- Apple Developer Console にログインし、アプリの Identifier (App ID) を選択
- "Capabilities" タブから "Associated Domains" を有効化（チェック）
- Provisioning Profile の更新:
- 変更した Identifier にリンクされている Provisioning Profile (開発用・配布用) を再生成（または編集して保存）します
- 更新された Provisioning Profile をダウンロードし、ビルドマシン（Mac）にインストールし直します
GitHub Pages + Jekyllの設定
ドメイン所有権があることを示すために Webサイト https://wwww.mywebsite.examle.com/ でアプリを開くため、サーバー側（GitHub Pages）に設定を行います。
GitHub Pages の設定:
.well-knownディレクトリを Jekyll が認識できるよう、_config.ymlにinclude: [".well-known"]を追加- GitHub Pages のカスタムドメインの設定によって Apex ドメイン => www 付ホスト / www 付ホスト => Apex ドメイン のいずれか一方にリダイレクトが発生します。
- iOS (Universal Links) はリダイレクトを許可しないため、アプリが処理するドメインの設定には注意が必要です。
検証ファイルの配置
Android用 (assetlinks.json):
https://www.mywebsite.example.com/.well-known/assetlinks.json を配置します。
[
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.myapp",
"sha256_cert_fingerprints": [
"<PRODUCTION_SHA256_FINGERPRINT>",
"<DEBUG_SHA256_FINGERPRINT>"
]
}
}
]
assetlinks.json の中身は Play Console の App integrity > App signing > Digital Asset Links JSON にあるので、コピーして利用することができます。ただし、開発ビルドでの動作確認を行う場合は、以下のように sha256_cert_fingerprints に開発用のフィンガープリントも追加する必要があります。
開発用の証明書のフィンガープリントは ~/.android/debug.keystore や ~/Library/Application Support/Xamarin/Mono for Android/debug.keystore などに格納されています。以下のコマンドで確認できます。パスワードは android です。
iOS用 (apple-app-site-association)
https://www.mywebsite.example.com/.well-known/apple-app-site-association (拡張子なし) を配置します。
{
"applinks": {
"details": [
{
"appIDs": ["XXXXXXXXXX.com.example.myapp"],
"components": [
{
"/": "/auth/email-verified"
}
]
}
]
}
}
上記は最小構成になりますが、フォーマットは変わることがあるので注意が必要です。 詳細な設定方法は以下のApple公式ドキュメントを参照してください。 Apple Developer - Supporting associated domains
Webページの作成
ディープリンクのURL (/auth/email-verified など) が 404 Not Found にならないように、適宜ファイルを設置します。
MAUI アプリの設定
MAUIプロジェクト側で、iOSとAndroidそれぞれに必要な設定を行います。
iOS (Platforms/iOS/Entitlements.plist)
Platforms/iOS/Entitlements.plist を開き、com.apple.developer.associated-domains キーに applinks:www.mywebsite.example.com (www付き) を指定しました。これは Developer Console で有効化した Capability と連動します。
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:www.mywebsite.example.com</string>
</array>
</dict>
</plist>
Android (Platforms/Android/MainActivity.cs)
AndroidManifest.xml を直接編集するのではなく、 MainActivity.cs に C# 属性で設定を行います。
[IntentFilter] 属性を追加し、DataScheme (https), DataHosts, DataPaths (対象パス), AutoVerify = true を指定します。
[Activity(Theme = "@style/Maui.SplashTheme",
MainLauncher = true,
ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density,
ShowForAllUsers = true,
ShowWhenLocked = true,
TurnScreenOn = true,
ScreenOrientation = ScreenOrientation.Portrait)]
[IntentFilter([Intent.ActionView],
Categories = [Intent.CategoryDefault, Intent.CategoryBrowsable],
DataScheme = "https",
DataHost = "www.mywebsite.example.com",
DataPath = "/auth/email-verified",
AutoVerify = true)]
public class MainActivity : MauiAppCompatActivity
{
}
MAUI 共通 (App.xaml.cs)
OnAppLinkRequestReceived メソッドをオーバーライドし、受け取った Uri を解析して Shell.Current.GoToAsync で目的のページに遷移するようにします。
動作確認
Android
実機にアプリをインストールし、URLをタップしてアプリが起動するか確認します。
うまくいかない場合は adb コマンドでドメインの検証ステータスを確認します。
失敗した場合はアプリをアンインストールして再インストールし、再度確認します。
# デバイスの確認
$ adb devices
List of devices attached
XXXXXXXXXXXXX device
emulator-5554 device
# 失敗例
$ adb -s XXXXXXXXXXXXX shell dumpsys package domain-preferred-apps
com.example.myapp:
ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Signatures: [XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX]
Domain verification state:
www.mywebsite.example.com: 1024
User 0:
Verification link handling allowed: true
Selection state:
Disabled:
www.mywebsite.example.com
Signatures に表示される SHA-256フィンガープリントが、assetlinks.json に記載したものと一致しているか確認します。
何らかの設定が間違っている場合は Domain verification state が 1024 (検証失敗) となります。
正しく設定できていると、以下のように Domain verification state が verified となります。
# 成功例
$ adb -s XXXXXXXXXXXXX shell dumpsys package domain-preferred-apps
com.example.myapp:
ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Signatures: [XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX]
Domain verification state:
www.mywebsite.example.com: verified
User all:
Verification link handling allowed: true
Selection state:
Disabled:
www.mywebsite.example.com
エミュレーターでの確認
エミュレータではドメインの検証が動かないようです (何かやり方があるかも知れません)。
アプリが正しくビルドできていれば、設定アプリの Apps > MyApp > Open by default 画面でドメインからドメインを追加できます。
エミュレーターでアプリ遷移時の動作を確認したい場合はこちらの方法が使えます。
これはあくまでエミュレーターでの代替手段です。プロダクションでは、実機での Domain verification state の動作確認を必ず行ってください
iOS
実機にアプリをインストールし、URLをタップしてアプリが起動するか確認します。
うまくいかない場合は、以下の手順でトラブルシューティングを行います。
まず、Apple の CDN が apple-app-site-association ファイルを正しくキャッシュしているかを確認します。
CDN のキャッシュには時間がかかる場合があるため、すぐに反映されないことがあるようです。
$ curl https://app-site-association.cdn-apple.com/a/v1/www.mywebsite.example.com
{
"applinks": {
"details": [
{
"appIDs": ["XXXXXXXXXX.com.example.myapp"],
"components": [
{
"/": "/auth/email-verified"
}
]
}
]
}
}
次に、設定アプリの デベロッパ > ユニバーサルリンク > 診断 に移動し、https://www.mywebsite.example.com/auth/email-verified を入力して診断を実行します。
結果がOKなら、設定は正しく行われています。
それでもうまくいかない場合は、URLをタップするアプリを変更したり、デフォルトブラウザをSafariに変更したりしてみてください。
シミュレーターでの確認
シミュレーターでは Universal Links の動作確認ができないようです。