カスタムタスクのQuick Linkを作成する

カスタムタスクのQuick Linkを作成する

Quick Linkを生成すると、カスタムスキル内の特定のカスタムタスクにユーザーを誘導し、入力パラメーターを渡すことができます。たとえば、トリビアスキルの新しいトリビアカテゴリーや公開したばかりの新しいオーディオコンテンツに、ユーザーが直接アクセスできるように誘導することができます。ほかにも、オンライン注文サービスと連携したスキルで注文を追跡する機能があれば、Quick Linkを介して注文サービスのサイトからスキルに注文IDを渡すことができます。これにより、スキルを使用しているユーザーは注文の追跡ができます。

カスタムタスクのQuick Linkの利用可能状況と要件は、カスタムスキルのQuick Linkとほぼ同じですが、以下の点が追加されます。

  • デバイス： ユーザーがQuick Linkを使用してスキルを起動できるデバイスは、 Echo（すべてのバージョン）、Echo Tap、Echo Dot（すべてのバージョン）、Echo Show（すべてのバージョン）、Echo Spot、Fire TVです。
  • ロケール： en_AU, en_CA, en_IN, en_GB, en_US, fr_CA, fr_FR, de_DE, hi_IN, it_IT, ja_JP, pt_BR, es_ES, es_MX, es_USに向けて作成されたカスタムスキルで利用できます。

スキルが満たす必要のある要件は次のとおりです。

  • 子ども向けスキルとHIPAAスキルで、Quick Linkを使うことはできません。

カスタムタスクが満たす必要のある要件は次のとおりです。

カスタムタスクを作成する

スキルにカスタムタスクを追加するの手順に従って、スキルにカスタムタスクを構築します（まだ行っていない場合）。

タスクタイトルと入力パラメーターにわかりやすい文字列を追加します。タスクのQuick Links for Alexaのウェブページで、この文字列がユーザーに表示されます。

  • タスクタイトル： infoオブジェクトのx-amzn-display-detailsフィールドは、カスタム拡張フィールドです。タスクタイトルにわかりやすい文字列を追加し、オプションでローカライズしたタイトルを割り当てることがきます。x-amzn-display-details値が指定されない場合、タイトルフィールドのデフォルト値が使用されます。
  • 入力パラメーター： タスクコンポーネントのinputプロパティにあるx-amzn-display-detailsフィールドは、カスタム拡張フィールドです。タスクの入力パラメーターにわかりやすい文字列を追加し、オプションでローカライズしたパラメーターを割り当てることができます。x-amzn-display-detailsフィールドが指定されない場合、propertiesフィールド内のプロパティ名が使用されます。

詳細については、タスク定義ファイルを作成するを参照してください。

カスタムタスクのQuick Linkに使用するURLの構文は、https://alexa-skills.amazon.<domain>/apis/custom/skills/<skill-id>/tasks/<custom-task-name>/versions/<task-version>?<task-input-key1>=<task-input-value1>&<task-input-key2>=<task-input-value2>です。

フィールド 説明 型 必須
domain リンクに含まれる、各マーケットプレイスに対応するドメイン。 文字列 ◯
skill-id スキルのスキルID。 文字列 ◯
custom-task-name カスタムタスクの内部名。 文字列 ◯
task-version カスタムタスクのバージョン番号。 文字列 ◯
task-input-key1 カスタムタスクの第1パラメーターの名前。 文字列 ✕
task-input-value1 カスタムタスクの第1パラメーターの値。 文字列 ✕

カスタムタスクのQuick Linkを作成する

  1. 公開中のカスタムスキルのskill-idを確認します。
    1. Alexa開発者コンソールに移動します。
    2. 必要に応じて、ログインします。
    3. スキルタブで、スキル名の下にあるスキルIDの表示リンクをクリックします。
    4. 前述の構文を使用し、<skill-id>を前の手順で確認したスキルIDに置き換えます。
  2. トップレベルドメイン（domain）を確認します。
    1. スキルが米国以外のマーケットプレイスで利用できる場合は、スキルのクイックリンクURLに異なるドメインを設定し、マーケットプレイスごとに個別のQuick Linkを作成することをお勧めします。
    2. スキルのQuick Linkは、AU、BR、CA、DE、ES、FR、GB、IN、IT、JP、MX、およびUSのマーケットプレイスで生成できます。
    3. スキルのQuick Linkを表示するマーケットプレイスごとに、以下の表からURLドメインを選択し、前述の構文の<domain>部分を置き換えます。
      マーケットプレイス ドメイン
      AU .com.au
      BR .com.br
      CA .ca
      DE .de
      ES .es
      FR .fr
      GB .co.uk
      IN .in
      IT .it
      JP .co.jp
      MX .com.mx
      US .com
  3. スキルIDをURLに追加します。
  4. カスタムタスク名とバージョンを追加します。

カスタムタスクで<task-input-key> = <task-input-value>という入力パラメーターと値のペアが必要な場合は、標準URLクエリ文字列として含めることができます。タスクパラメーターは、文字列、数値、ブール値などの単純なデータ型である必要があります。

トラフィック分析にキャンペーンアトリビューションを追加する

さまざまなオンラインチャネルで表示された個々のリンクからのスキルの起動回数を追跡できます。スキルのカスタムタスクの入力パラメーターとQuick Link URLのクエリ文字列パラメーターを組み合わせて、起動を追跡します。

各種のソーシャルメディアチャネルなど、オンラインで実行している個々の広告キャンペーンのトラフィック分析をスキルを通じて取得できます。そのためには、Quick Linkとして表示するスキルの各カスタムタスクに、a2z_refという名前の入力パラメーターを作成します。このパラメーターをQuick Link URLのクエリ文字列パラメーターとして使用できます。特定のソースにアトリビュートされるように、値を一意の文字列に設定します。任意の入力パラメーターを作成してアトリビューション文字列を渡すこともできますが、キャンペーンアトリビューション専用にa2z_ref入力パラメーターが用意されています。このパラメーターは、Quick Links for Alexaのウェブページには表示されません。

以下は、トラフィック分析にキャンペーンアトリビューションを追加する手順です。

Quick Linkにアトリビューションパラメーターを追加する方法

  1. スキルにカスタムタスクを作成するには、タスク定義ファイルを作成するの手順に従います。既存のカスタムタスクがある場合は、そのタスクを使用することもできます。
  2. カスタムタスクのタスク定義ファイルで、string型のa2z_refという名前の入力パラメーターを作成します。

  3. このタスクの機能をスキルのハンドラーコードに実装します。

    ユーザーに起動エクスペリエンスのみを提供する場合は、LaunchRequestハンドラーのcan_handleロジックに新しいチェックを追加するだけです。このアクションは、これがカスタムタスクのリクエストかどうかをチェックします。以下のPythonは、その新しいチェックの例です。

       def can_handle(self, handler_input): 
   return is_request_type("LaunchRequest")(handler_input)\ 
   and handler_input.request_envelope.request.task.name == "<タスク名>"
  4. 新規または変更したカスタムタスクを公開にするには、スキルを公開します。
  5. カスタムタスクが公開されたら、このタスクのQuick Linkを作成し、URLにa2z_refパラメーターを含めて、オンラインで表示するキャンペーン（広告キャンペーンなど）に応じて値を割り当てます。

ユーザーがこのQuick Linkをクリックしてスキルを起動すると、a2z_refパラメーターの値を入力パラメーターとして持つリクエストがカスタムタスクに渡されます。そのパラメーターを使用して、対応するキャンペーンに起動をアトリビュートさせることができます。

ベストプラクティス： カスタムタスクパラメーター

カスタムタスクではディープリンクがサポートされているため、Quick Linkの機能を強化することができます。ただし、スキルのタスクを使用して、開発者やユーザーのプライバシーとセキュリティを保護する必要があります。カスタムタスクパラメーターを設計し、これらのタスクにQuick Linkを生成する場合は、次の推奨事項を考慮してください。

  • 入力パラメーターに適したデータ型を選択します。たとえば、入力パラメーターが常に数値になる場合は、タスクの定義時にパラメーターに数値データ型を選択します。
  • 可能であれば、自由形式の文字列を受け入れるのではなく、入力パラメーターで使用する値を列挙します。そうすると、この列挙にマッピングされていない値は、Quick Linkクエリ文字列からの取得を拒否できます。使用可能な値を列挙することにより、Quick Linkクエリパラメーターの意図的な悪用を防止できます。
  • a2z_refアトリビューションパラメーターを使用する場合は、マーケティングチームに役立つような定義済みの文字列パターンを使用し、このパターンと一致しない値をすべて拒否します。たとえば、<website-or-app-name>_<campaign>というパターンが考えられます。ここで、<website-or-app-name>は、リンクを表示するウェブサイトまたはアプリケーションの名前を表す文字列です。<campaign>は、マーケティングキャンペーン用に考案した名前を表す文字列です。このパターン（アンダースコアを含む）を常に使用するようマーケターに要求することで、カスタムタスクのハンドラーロジックで受け取る入力値を検証できます。
  • ユーザー個人を特定できる情報（PII）を示す可能性のあるパラメーター名または値を含めないでください。PIIデータには、ユーザーの名前、住所、メールアドレス、社会保障番号などが含まれます。
  • 場合によっては、エンコードした値をURLパラメーターで渡し、カスタムタスクのハンドラーロジックでデコードすることもできます。その場合は、入力パラメーターの説明文字列で、値がエンコードされていることを常に示す必要があります。たとえば、割引オファーIDをエンコードして、カスタムタスクURLのパラメーターとして渡し、ユーザーに表示される前にハンドラーロジックでIDをデコードするとします。その場合、カスタムタスクの入力パラメーターに人が読める名前（「秘密のオファーID」など）を選択すると、Amazonのページでユーザーに 「秘密のオファーID：a1b2c3」のような文字列を表示できます。この文字列により、ユーザーとスキルの両方を保護しながら、この値は表示すべきものではないとユーザーに伝えることができます。

このページは役に立ちましたか？

最終更新日: 2022 年 06 月 30 日