このページは Cloud Translation API によって翻訳されました。

ショートカットを作成する

ショートカットは、ユーザーがアプリの一部にすばやくアクセスできるように、特定の種類のコンテンツを配信します。

アプリのショートカットと固定ショートカットのコントラストを示す画像 — **図 1.** アプリのショートカットと固定ショートカット。

ショートカットでコンテンツを配信する方法は、ユースケースと、ショートカットのコンテキストがアプリ主導かユーザー主導かによって異なります。静的ショートカットのコンテキストは変更されず、動的ショートカットのコンテキストは常に変更されますが、どちらの場合もアプリはコンテキストを使用します。固定ショートカットなど、アプリからのコンテンツ配信方法をユーザーが選択する場合、コンテキストはユーザーによって定義されます。次のシナリオでは、ショートカットの種類ごとにユースケースをいくつか説明します。

静的ショートカットは、ユーザーがアプリを操作している間、一貫した構造を使用してコンテンツにリンクするアプリに最適です。ほとんどのランチャーは一度に 4 つのショートカットしか表示しないため、ユーザーが特定の方法でカレンダーやメールを表示する場合など、ルーティンタスクを一貫した方法で実行するには静的ショートカットが役立ちます。
動的ショートカットは、コンテキストに依存するアプリのアクションに使用されます。コンテキスト依存のショートカットは、ユーザーがアプリ内で行う操作に合わせてカスタマイズされます。たとえば、ユーザーが起動時に現在のレベルから開始できるゲームを作成する場合、ショートカットを頻繁に更新する必要があります。動的ショートカットを使用すると、ユーザーがレベルをクリアするたびにショートカットを更新できます。
固定ショートカットは、特定のユーザー主導アクションに使用されます。たとえば、ユーザーが特定のウェブサイトをランチャーに固定する場合などです。これは、ユーザーがカスタム操作（ブラウザのデフォルトのインスタンスを使用するよりも速く 1 ステップでウェブサイトに移動するなど）を実行できるため便利です。

静的ショートカットを作成する

静的ショートカットは、アプリ内の一般的な操作へのリンクを提供します。これらの操作は、アプリの現在のバージョンの全期間を通じて一貫している必要があります。静的ショートカットには、送信済みメッセージの表示、アラームの設定、ユーザーの 1 日のエクササイズアクティビティの表示などが適しています。

静的ショートカットを作成する手順は次のとおりです。

アプリの AndroidManifest.xml ファイルで、インテントフィルタが android.intent.action.MAIN アクションと android.intent.category.LAUNCHER カテゴリに設定されているアクティビティを探します。

このアクティビティに、アプリのショートカットが定義されているリソースファイルを参照する <meta-data> 要素を追加します。

  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
            package="com.example.myapplication">
    <application ... >
      <activity android:name="Main">
        <intent-filter>
          <action android:name="android.intent.action.MAIN" />
          <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
        
        <meta-data android:name="android.app.shortcuts"
                   android:resource="@xml/shortcuts" /> 
      </activity>
    </application>
  </manifest>

注: activity-alias を使用する場合は、 targetActivity 属性を使用して、ターゲットとするアクティビティではなくアクティビティエイリアスでメタデータを定義してください。

res/xml/shortcuts.xml という名前の新しいリソースファイルを作成します。

新しいリソースファイルに、<shortcut> 要素のリストを含む <shortcuts> ルート要素を追加します。各 <shortcut> 要素には、静的ショートカットに関する情報（アイコン、説明ラベル、アプリ内で起動するインテントなど）を含めます。

  <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
    <shortcut
      android:shortcutId="compose"
      android:enabled="true"
      android:icon="@drawable/compose_icon"
      android:shortcutShortLabel="@string/compose_shortcut_short_label1"
      android:shortcutLongLabel="@string/compose_shortcut_long_label1"
      android:shortcutDisabledMessage="@string/compose_disabled_message1">
      <intent
        android:action="android.intent.action.VIEW"
        android:targetPackage="com.example.myapplication"
        android:targetClass="com.example.myapplication.ComposeActivity" />
      <!-- If your shortcut is associated with multiple intents, include them
           here. The last intent in the list determines what the user sees when
           they launch this shortcut. -->
      <categories android:name="android.shortcut.conversation" />
      <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
    </shortcut>
    <!-- Specify more shortcuts here. -->
  </shortcuts>

属性値をカスタマイズする

次のリストでは、静的ショートカット内のさまざまな属性について説明します。android:shortcutId と android:shortcutShortLabel に値を指定します。その他の値はすべて省略可能です。

android:shortcutId

ShortcutManager オブジェクトがショートカットに対してオペレーションを実行するときにショートカットを表す文字列リテラル。

注: この属性の値を、@string/shortcut_id などのリソース文字列に設定することはできません。

android:shortcutShortLabel

ショートカットの目的を説明する簡潔なフレーズ。可能であれば、この簡単な説明は 10 文字以内にしてください。

詳細については、setShortLabel() をご覧ください。

注: この属性の値は、@string/shortcut_short_label などのリソース文字列にする必要があります。

android:shortcutLongLabel

ショートカットの目的を説明する詳細なフレーズ。十分なスペースがある場合、ランチャーは android:shortcutShortLabel ではなくこの値を表示します。可能であれば、この詳しい説明は 25 文字以内にしてください。

詳細については、setLongLabel() をご覧ください。

注: この属性の値は、@string/shortcut_long_label などのリソース文字列にする必要があります。

android:shortcutDisabledMessage

無効化されたショートカットをユーザーが起動しようとしたときに、サポートされているランチャーに表示されるメッセージ。このメッセージでは、ショートカットが無効になっている理由をユーザーに説明する必要があります。android:enabled が true の場合、この属性の値は無視されます。

注: この属性の値は、@string/shortcut_disabled_message などのリソース文字列にする必要があります。

android:enabled

サポートされているランチャーからユーザーがショートカットを操作できるかどうかを指定します。android:enabled のデフォルト値は true です。false に設定する場合は、ショートカットを無効にする理由を説明する android:shortcutDisabledMessage を設定します。このようなメッセージを表示する必要がないと思われる場合は、XML ファイルからショートカットを完全に削除してください。

android:icon

ランチャーがユーザーにショートカットを表示する際に使用するビットマップまたはアダプティブアイコン。この値は、画像へのパスか、画像を含むリソースファイルのパスです。パフォーマンスと一貫性を向上させるため、可能な限りアダプティブアイコンを使用してください。

内部要素を設定する

アプリの静的ショートカットをリストする XML ファイルは、各 <shortcut> 要素内で次の要素をサポートします。定義する静的ショートカットごとに intent 内部要素を含める必要があります。

intent

ユーザーがショートカットを選択したときにシステムが起動するアクション。このインテントでは、android:action 属性の値を指定する必要があります。

注: この intent 要素に文字列リソースを含めることはできません。

1 つのショートカットに複数のインテントを指定できます。詳細については、複数のインテントとアクティビティを管理する、インテントを設定する、TaskStackBuilder クラスのリファレンスをご覧ください。

categories

新しいチャットメッセージの作成など、アプリのショートカットで実行するアクションの種類をグループ化します。

サポートされているショートカットカテゴリの一覧については、ShortcutInfo クラスのリファレンスをご覧ください。

capability-binding

ショートカットにリンクされている機能を宣言します。

上記の例では、CREATE_MESSAGE に対して宣言された機能（App Actions の組み込みインテント）にショートカットがリンクされています。このケーパビリティバインディングにより、ユーザーは Google アシスタントの音声コマンドを使用してショートカットを呼び出すことができます。

動的ショートカットを作成する

動的ショートカットは、アプリ内のコンテキストに応じた特定の操作へのリンクを提供します。これらの操作は、アプリの使用時とアプリの実行中に変更される場合があります。動的ショートカットは、特定のユーザーへの発信、特定の場所へのナビゲーション、ユーザーの最後のセーブポイントからのゲームの読み込みなどに適しています。動的ショートカットを使用して会話を開くこともできます。

ShortcutManagerCompat Jetpack ライブラリは ShortcutManager API のヘルパーで、これを使用してアプリの動的ショートカットを管理できます。ShortcutManagerCompat ライブラリを使用すると、ボイラープレートコードを削減し、Android バージョン間でショートカットの一貫性を確保できます。また、このライブラリは、動的ショートカットをプッシュするためにも必要です。これにより、 Google Shortcuts Integration Library を使用して、アシスタントなどの Google サーフェス上に動的ショートカットを表示できるようになります。

ShortcutManagerCompat API を使用すると、アプリは動的ショートカットを使用して次のオペレーションを実行できます。

プッシュと更新: pushDynamicShortcut() を使用して動的ショートカットを公開、更新します。同じ ID の動的ショートカットや固定ショートカットがすでに存在する場合は、それぞれの可変ショートカットが更新されます。
削除: removeDynamicShortcuts() を使用して動的ショートカットのセットを削除します。removeAllDynamicShortcuts() を使用して、すべての動的ショートカットを削除します。

ショートカットに対するオペレーションの実行について詳しくは、ショートカットを管理すると ShortcutManagerCompat リファレンスをご覧ください。

動的ショートカットを作成してアプリに関連付ける例を次に示します。

Kotlin


val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

Java


ShortcutInfoCompat shortcut = new ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

Google Shortcuts Integration Library を追加する

Google Shortcuts Integration Library は、オプションの Jetpack ライブラリです。これにより、ランチャーなどの Android サーフェスとアシスタントなどの Google サーフェスに表示できる動的ショートカットをプッシュできます。このライブラリを使用すると、ユーザーは、アプリ内の特定のコンテンツにすばやくアクセスしたり、アクションを再生したりするためのショートカットを見つけることができます。

たとえば、メッセージアプリでは、ユーザーが「Alex」という名前の連絡先にメッセージを送信した後に、その連絡先の動的ショートカットがプッシュされます。動的ショートカットが押された後、ユーザーがアシスタントに「OK Google, ExampleApp でアレックスにメッセージを送信して」と話しかけると、アシスタントは ExampleApp を起動し、Alex にメッセージを送信するよう自動的に構成できます。

このライブラリでプッシュされた動的ショートカットには、デバイスごとに適用されるショートカットの制限は適用されません。これにより、ユーザーがアプリ内で関連する操作を完了するたびに、アプリはショートカットをプッシュできます。このように頻繁にショートカットをプッシュすると、Google がユーザーの使用パターンを理解し、状況に応じた適切なショートカットを提案できるようになります。

たとえば、Google アシスタントは、フィットネストラッキングアプリからプッシュされたショートカットから、ユーザーが通常毎朝実行するものを学習し、ユーザーが午前中にスマートフォンを持ち上げると「ランニングを開始」するショートカットを積極的に提案します。

Google Shortcuts Integration Library 自体には、アドレス指定可能な機能はありません。このライブラリをアプリに追加すると、ShortcutManagerCompat を使用してアプリがプッシュするショートカットを Google サーフェスで受け取れます。

アプリでこのライブラリを使用する手順は次のとおりです。

AndroidX ライブラリをサポートするように gradle.properties ファイルを更新します。

      
      android.useAndroidX=true
      # Automatically convert third-party libraries to use AndroidX
      android.enableJetifier=true

app/build.gradle で、Google Shortcuts Integration Library と ShortcutManagerCompat の依存関係を追加します。

      
      dependencies {
        implementation "androidx.core:core:1.6.0"
        implementation 'androidx.core:core-google-shortcuts:1.0.0'
        ...
      }

ライブラリ依存関係を Android プロジェクトに追加すると、アプリは ShortcutManagerCompat の pushDynamicShortcut() メソッドを使用して、ランチャーと Google サーフェスに表示できる動的ショートカットをプッシュできます。

注: Google Shortcuts Integration Library で動的ショートカットをプッシュするには、pushDynamicShortcut を使用することをおすすめします。アプリは他のメソッドを使用してショートカットを公開することもできますが、ショートカットの上限に達すると、公開に失敗する可能性があります。

固定ショートカットを作成する

Android 8.0（API レベル 26）以降では、固定ショートカットを作成できます。静的ショートカットや動的ショートカットとは異なり、固定ショートカットはサポートされているランチャーに個別のアイコンとして表示されます。図 1 に、この 2 種類のショートカットの違いを示します。

アプリを使用して、サポートされているランチャーにショートカットを固定する手順は次のとおりです。

isRequestPinShortcutSupported() を使用して、デバイスのデフォルトランチャーがショートカットのアプリ内固定をサポートしていることを確認します。
ショートカットが存在するかどうかに応じて、次の 2 つの方法のいずれかで ShortcutInfo オブジェクトを作成します。
1. ショートカットが存在する場合は、既存のショートカットの ID のみを含む ShortcutInfo オブジェクトを作成します。ショートカットに関連するその他の情報はすべて、自動的に検出されて固定されます。
2. 新しいショートカットを固定する場合は、新しいショートカットの ID、インテント、短いラベルを含む ShortcutInfo オブジェクトを作成します。
注: 固定ショートカットのバックアップと復元は自動的に行われるため、これらのショートカットの ID には、他のデバイスでは意味をなさない、ローカルで生成された識別子ではなく、不変の定数文字列またはサーバー側の識別子を含める必要があります。
requestPinShortcut() を呼び出して、デバイスのランチャーにショートカットを固定します。このプロセス中に、PendingIntent オブジェクトを渡すことができます。このオブジェクトは、ショートカットが正常に固定された場合にのみアプリに通知します。

注: ユーザーがショートカットをランチャーに固定できない場合、アプリはコールバックを受け取りません。

ショートカットが固定された後、アプリは updateShortcuts() メソッドを使用してコンテンツを更新できます。詳しくは、ショートカットを更新するをご覧ください。

次のコードスニペットは、固定ショートカットを作成する方法を示しています。

注: ShortcutManager クラスのインスタンスは、引数 ShortcutManager.class が指定された Context.getSystemService(Class) か、引数 Context.SHORTCUT_SERVICE が指定された Context.getSystemService(String) を使用して取得する必要があります。

Kotlin

val shortcutManager = getSystemService(ShortcutManager::class.java)

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

Java

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0);

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

注: Android 7.1（API レベル 25）以下で動作するサポートライブラリ API の isRequestPinShortcutSupported() および requestPinShortcut() もご覧ください。サポートライブラリは、非推奨の EXTRA_SHORTCUT_INTENT エクストラにフォールバックして、固定プロセスを試みます。

カスタムショートカットアクティビティを作成する

「Gmail のランチャーアイコンをホーム画面に追加しますか？」というプロンプトを表示するカスタムダイアログアクティビティの画像カスタムオプションは、[スキップ] と [アイコンを追加] です。 — **図 2.** カスタムアプリのショートカットダイアログアクティビティの例。

また、カスタムオプションと確認ボタンを備えたショートカットの作成に役立つ特別なアクティビティを作成することもできます。図 2 は、Gmail アプリでのこのタイプのアクティビティの例を示しています。

アプリのマニフェストファイルで、アクティビティの <intent-filter> 要素に ACTION_CREATE_SHORTCUT を追加します。この宣言により、ユーザーがショートカットを作成しようとしたときに次の動作が設定されます。

システムがアプリの特別なアクティビティを開始します。
ユーザーがショートカットのオプションを設定します。
ユーザーが確認ボタンを選択します。
アプリは createShortcutResultIntent() メソッドを使用してショートカットを作成します。このメソッドは Intent を返します。アプリは、setResult() を使用して、以前に実行中のアクティビティにそれをリレーします。
アプリは、カスタマイズされたショートカットの作成に使用されたアクティビティで finish() を呼び出します。

同様に、インストール後またはアプリの初回起動時に、固定ショートカットをホーム画面に追加するようユーザーに求めることができます。この方法は、ユーザーが通常のワークフローの一部としてショートカットを作成できるため効果的です。

ショートカットをテストする

アプリのショートカットをテストするには、ショートカットをサポートするランチャーを備えたデバイスにアプリをインストールします。次に、以下の操作を行います。

アプリのランチャーアイコンを長押しすると、アプリに定義したショートカットが表示されます。
ショートカットをドラッグして、デバイスのランチャーに固定します。

ショートカットを作成する

静的ショートカットを作成する

属性値をカスタマイズする

内部要素を設定する

動的ショートカットを作成する

Kotlin

Java

Google Shortcuts Integration Library を追加する

固定ショートカットを作成する

Kotlin

Java

カスタム ショートカット アクティビティを作成する

ショートカットをテストする

カスタムショートカットアクティビティを作成する