プロアクティブサジェスチョンAPI
Alexaマルチモーダルデバイスのホーム画面を通じて、Alexa Smart Propertiesの施設の運営者は、ブランディングを高めたり、製品やサービスのアップセル(ハッピーアワーやスパサービスの提供など)を実現したり、イベント、アップデート、スキルに関する情報をゲストに提供したりできます。
ソリューションインテグレーターは、AlexaプロアクティブサジェスチョンREST APIを使用して、施設のマネージャーが視覚コンテンツをサジェスチョンとしてAlexaに提供できるようにすることが可能です。Alexaは、これらのサジェスチョンからコンテンツ項目を選択し、ユーザーのデバイスのホーム画面に表示します。サジェスチョンの視覚エクスペリエンスを作成するには、Alexa Presentation Language(APL)を使用します。
DoNotDisturb
モードの場合、プロアクティブサジェスチョンのキャンペーンは、ユーザーが直近でAlexaと対話した場合にのみ表示されます。Alexaとの対話がない状態が数分間続くと、デバイスは時計の表示に戻ります。APIエンドポイント
リクエストヘッダーでは、組織が所在する地域に応じて、Host
を以下のいずれかに設定してください。
国 | エンドポイント |
---|---|
カナダ、米国 |
|
ドイツ、スペイン、フランス、イタリア、英国 |
|
日本 |
|
認証
すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。
操作
プロアクティブサジェスチョンAPIには、以下の操作が用意されています。
説明 | HTTPメソッドとパス |
---|---|
| |
| |
| |
| |
|
キャンペーンを作成する
ターゲット受信者へのサジェスチョンとしてコンテンツをレンダリングするキャンペーンを作成します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
POST /v1/proactive/campaigns HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエスト本文の形式
リクエスト本文には、サジェスチョンをその受信者およびスケジュールの詳細と共にカプセル化する、キャンペーンエンティティが含まれます。以下の例は、キャンペーンエンティティを示しています。
{
"suggestion": {
"variants": [{
"placement": {
"channel": "HOME"
},
"content": {
"values": [{
"locale": "ja-JP",
"document": {},
"datasources": {}
}]
}
}]
},
"targeting": {
(タイプがユニットのポリモーフィックオブジェクト)
},
"scheduling": {
"activationWindow": {
"start": "2021-01-01T10:00:00.00Z",
"end": "2021-01-31T10:00:00.00Z"
}
}
}
リクエスト本文の例
以下は、キャンペーンのリクエスト本文の例です。この例は、英語(米国)のデバイスではen-US
のコンテンツを表示し、日本語のデバイスではja-JP
のコンテンツを表示します。デバイスには、ロケールごとに常に1つのキャンペーンのみが表示されます。
{
"suggestion": {
"variants": [
{
"placement": {
"channel": "HOME"
},
"content": {
"values": [
{
"locale": "ja-JP",
"document": {
"type": "Link",
"src": "<ドキュメントへのリンクのプレースホルダー>"
},
"datasources": {
"displayText": {
"primaryText": "Example notification title.",
"secondaryText": "Example notification text.",
"action": {
"type": "SkillConnection",
"uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
"input": {}
}
},
"background": {
"backgroundImageSource": "https://www.example.com/image.jpg"
}
}
},
{
"locale": "ja-JP",
"document": {
"type": "Link",
"src": "<ドキュメントへのリンクのプレースホルダー>"
},
"datasources": {
"displayText": {
"primaryText": "サンプルの通知タイトルです。",
"secondaryText": "サンプルの通知テキストです。",
"action": {
"type": "SkillConnection",
"uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
"input": {}
}
},
"background": {
"backgroundImageSource": "https://www.example.com/image.jpg"
}
}
}
]
}
}]
},
"targeting": {
"type": "UNITS",
"values": [
{
"id": "amzn1.alexa.unit.did.unitId"
}
]
},
"scheduling": {
"activationWindow": {
"start": "2021-01-01T10:00:00.00Z",
"end": "2021-01-31T10:00:00.00Z"
}
}
}
リクエスト本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
Alexaがユーザーにプロアクティブに配信できる情報。 |
オブジェクト |
◯ |
|
ユーザーに提供するサジェスチョンバリアントのリスト。リストには1つ以上のバリアントが含まれている必要があります。ただし、1つの配信先チャンネルに提供できるバリアントは最大1つです。 |
配列 |
◯ |
|
コンテンツをレンダリングする場所。 |
オブジェクト |
◯ |
|
チャンネルの名前。現在サポートされている値は |
文字列 |
◯ |
|
デフォルトのコンテンツタイプに固有のローカライズされたプレゼンテーションデータを含むオブジェクトの配列。少なくとも1つのローカライズされたプレゼンテーションデータ要素を提供する必要があります。さまざまなロケールに対応するために、この配列に複数のオブジェクトを指定できます。ただし、1つのロケールに対して複数のオブジェクトを定義することはできません。デバイスでは、そのデバイスのロケールに一致する最初のオブジェクトが表示されます。 |
配列 |
◯ |
|
コンテンツがレンダリングされるロケール。IETF BCP 47形式で表します。 |
文字列 |
◯ |
|
レンダリングに使用するAPLドキュメントへのリンク。詳細については、RenderDocumentでリンクドキュメントを使用するを参照してください。すべてのAPL機能がサポートされるわけではありません。 |
文字列 |
◯ |
|
APLドキュメントのタイプ。 |
文字列 |
◯ |
|
APLドキュメントのリンク。サポートされている複数のテンプレートから選択できます。使用するテンプレートに応じて、このプロパティを次の特定のドキュメントリンクに設定します。
|
文字列 |
◯ |
|
APLドキュメントにデータをバインドするほかのオブジェクトを含むことができるオブジェクト。 |
データソースオブジェクトのマップ |
◯ |
|
キャンペーンの受信者を定義するポリモーフィックオブジェクト。ターゲットのタイプはユニットです。 |
オブジェクト |
◯ |
|
キャンペーンのスケジュール情報。このフィールドが存在しない場合、デフォルトの開始時刻は現在の時刻、終了時刻は現在の時刻の24時間後になります。 |
オブジェクト |
✕ |
|
キャンペーンがアクティブになる期間を指定するタイムウィンドウオブジェクト。 |
オブジェクト |
〇( |
|
タイムウィンドウの開始時刻。ISO 8601形式(YYYY-MM-DDThh:mm:ssZ)に則ったRFC 3339プロファイルを使用する文字列です。デフォルト値は現在の時刻です。 |
文字列 |
✕ |
|
タイムウィンドウの終了時刻。ISO 8601形式(YYYY-MM-DDThh:mm:ssZ)に則ったRFC 3339プロファイルを使用する文字列です。開始時刻と同じかそれ以降の時刻を表している必要があります。デフォルト値は、現在の時刻から24時間後です。 |
文字列 |
✕ |
ユニットターゲット
キャンペーンのターゲットとなるユニットです。
{
"type": "UNITS",
"values": [
{
"id": "amzn1.alexa.unit.did.unitId"
}
]
}
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
適用されるターゲット条件のタイプ。有効な値は |
文字列 |
◯ |
|
ルームのユニットIDを含むオブジェクトのリスト。ユニットIDは 注: 各ユニットIDは、施設やルームタイプではなく、ルームを表すものでなければなりません。
|
配列 |
◯ |
|
ルームのユニットID。 |
文字列 |
◯ |
units.items
のリストを含む形式)も引き続き使用できます。ただし、新しい実装では、上に示した現在の形式のAPIを使用してください。成功応答ヘッダー
HTTP/1.1 202 Accepted
Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
◯ |
応答本文の形式
{
"campaignId": "{exampleId}"
}
応答本文のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
キャンペーンのキャンペーンID。キャンペーンを削除するときやキャンペーンを取得するときは、このIDを使用します。 |
文字列 |
referenceId
が返されます。これは、Amazonがリクエストに対して生成する一意の識別子です。HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
201 |
Created |
キャンペーンが正常に作成されました。 |
400 |
Bad Request |
リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
401 |
Unauthorized |
アクセストークンがないか、期限切れか、無効です。 |
403 |
Forbidden |
アクセストークンは有効ですが、必要なLWAスコープの権限をユーザーが持っていません。 |
429 |
Too Many Requests |
リクエストが制限されています。 |
500 |
Internal Server Error |
内部サービスエラーのためリクエストを処理できませんでした。 |
503 |
Service Unavailable |
サービスが一時的に使用できません。 |
キャンペーンのリストを取得する
作成したキャンペーンのリストを取得します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
GET /v1/proactive/campaigns?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエスト本文の形式
なし。
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
表示する結果の最大数。値は1~10の間で指定します。デフォルト値は10です。 |
整数 |
✕ |
|
前回のキャンペーンリストの取得に対する応答で、応答オブジェクトに返された継続トークン。 |
文字列 |
✕ |
成功応答のヘッダー
Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
◯ |
応答本文の形式
{
"results": [
{
"campaignId": "campaignId",
"suggestion": {
"variants": [{
"placement": {
"channel": "HOME"
},
"content": {
"values": [{
"locale": "en-US",
"document": {},
"datasources": {}
}]
}
}]
},
"targeting": {
(タイプがユニットのポリモーフィックオブジェクト)
},
"scheduling": {
"activationWindow": {
"start": "2021-01-01T10:00:00.00Z",
"end": "2021-01-31T10:00:00.00Z"
}
},
"validationStatus": {
"value": "string enum", // IN_PROGRESS、APPROVED、REJECTED
"reason": "Explanation"
}
},
{
... (別のキャンペーンおよびステータス)...
}
],
"paginationContext": {
"nextToken": "(前回の呼び出しで返されたトークン)"
}
}
応答本文のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
作成したキャンペーンのリストと、それぞれの検証ステータス。 |
配列 |
|
キャンペーンの作成時に指定した詳細。フィールドについては、キャンペーン作成時のリクエスト本文の形式を参照してください。 |
オブジェクト |
|
キャンペーンの最新の検証ステータス。 |
オブジェクト |
|
キャンペーンの最新の検証ステータスを表す列挙値。有効な値は |
文字列 |
|
検証ステータスの値の説明(該当する場合)。 |
文字列 |
|
ページ分割情報を含むオブジェクト。存在しない場合、すべての評価結果が既に返されています。 |
オブジェクト |
|
キャンペーンのリストを取得する次回の呼び出しで使用するための継続トークン。 |
文字列 |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
202 |
Request Accepted |
リクエストが受け付けられました。 |
400 |
Bad Request |
リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
401 |
Unauthorized |
アクセストークンがないか、期限切れか、無効です。 |
403 |
Forbidden |
アクセストークンは有効ですが、必要なLWAスコープの権限をユーザーが持っていません。 |
429 |
Too Many Requests |
リクエストが制限されています。 |
500 |
Internal Server Error |
内部サービスエラーのためリクエストを処理できませんでした。 |
503 |
Service Unavailable |
サービスが一時的に使用できません。 |
キャンペーンを照会する
ユニットのリストに対してキャンペーンを照会します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、日本 |
米国 |
リクエストの形式
POST /v1/proactive/campaigns/query HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエスト本文の形式
以下のクエリは、1つ以上のユニットを使用してアクティブなサジェスチョンを返します。
{
"query": {
"and": [
{
"or": [
{
"match": {
"targeting.values.id": "U1"
}
},
{
"match": {
"targeting.values.id": "U2"
}
}
]
},
{
"match": {
"targeting.type": "UNITS"
}
}
]
},
"paginationContext": {
"maxResults": 10,
"nextToken": "paginationTokenString"
}
}
リクエスト本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
サジェスチョンを取得するためのフィルタリング条件を提供するオブジェクト。このオブジェクトには、
|
◯ | |
|
ページ分割情報を含むオブジェクト。 |
オブジェクト |
✕ |
|
1回のリクエストで返されるサジェスチョンの最大数。値は1~100の間で指定します。デフォルト値は10です。 |
整数 |
✕ |
|
前回の応答に続くデータがある場合に、後続データを取得するために使用するトークン。このフィールドには、nullまたはサーバーから返された有効な値を指定する必要があります。 |
文字列 |
✕ |
Queryオブジェクト
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
論理 |
配列 |
✕ |
|
論理 |
配列 |
✕ |
成功応答のヘッダー
HTTP/1.1 200 OK
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: sample-request-id-value
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
◯ |
応答本文の例
{
"paginationContext": {
"nextToken": "paginationTokenString"
},
"results": [
{
"campaignId": "sample-id",
"validationStatus": {
"value": "IN_PROGRESS",
"reason": "Explanation"
},
"suggestion": {
"variants": [
{
"placement": {
"channel": "HOME"
},
"content": {
"values": [
{
"locale": "en-US",
"document": {
"type": "Link",
"src": "<ドキュメントへのリンクのプレースホルダー>"
},
"datasources": {
"displayText": {
"primaryText": "Light and warm patio breakfast",
"secondaryText": "Breakfast is served until 11:30 am!"
}
}
},
{
"locale": "ja-JP",
"document": {
"type": "Link",
"src": "<ドキュメントへのリンクのプレースホルダー>"
},
"datasources": {
"displayText": {
"primaryText": "明るく暖かいテラスで朝食を",
"secondaryText": "朝食は午前11:30までご利用いただけます。"
}
},
"background": {
"backgroundImageSource": "https://url-of-image.jpg"
}
}
]
}
}
]
},
"targeting": {
"type": "UNITS",
"values": [
{
"id": "amzn1.alexa.unit.did.unitId"
}
]
},
"scheduling": {
"activationWindow": {
"start": "2021-01-01T10:00:00.00Z",
"end": "2021-01-31T10:00:00.00Z"
}
}
}
]
}
応答本文のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
ページ分割情報を含むオブジェクト。存在しない場合、すべての評価結果が既に返されています。 |
オブジェクト |
|
キャンペーンを照会する次回の呼び出しで使用するための継続トークン。このフィールドがnullの場合、すべての評価結果が既に返されています。このフィールドがnullでない場合、次のページにまだ評価結果があります。 |
文字列 |
|
ユニットに対して作成したキャンペーンのリストと、各キャンペーンの検証ステータス。 |
配列 |
|
キャンペーンID。 |
文字列 |
|
キャンペーンの最新の検証ステータス。 |
オブジェクト |
|
キャンペーンの最新の検証ステータスを表す列挙値。有効な値は |
文字列 |
|
検証ステータスの値の説明(該当する場合)。 |
文字列 |
|
ユーザーに配信するメッセージ。 |
オブジェクト |
|
ユーザーに提供するサジェスチョンバリアントのリスト。リストには1つ以上のバリアントが含まれている必要があります。 |
配列 |
|
コンテンツをレンダリングできる場所。 |
オブジェクト |
|
チャンネルの名前。現在サポートされている値は |
文字列 |
|
デフォルトのコンテンツタイプに固有のローカライズされたプレゼンテーションデータを含むオブジェクト。少なくとも1つのローカライズされたプレゼンテーションデータ要素が必要です。 |
配列 |
|
コンテンツがレンダリングされるロケール。IETF BCP 47形式で表します。 |
文字列 |
|
レンダリングに使用するAPLドキュメントへのリンク。詳細については、RenderDocumentでリンクドキュメントを使用するを参照してください。すべてのAPL機能がサポートされるわけではありません。 |
オブジェクト |
|
APLドキュメントのタイプ。 |
文字列 |
|
APLドキュメントのリンク。 |
文字列 |
|
APLドキュメントにデータをバインドするほかのオブジェクトを含むことができるオブジェクト。このオブジェクト内の固有のフィールドは、 |
オブジェクト |
|
キャンペーンの受信者を定義するポリモーフィックオブジェクト。ユニット、ユーザー、スキルサブスクライバーの3つのターゲットタイプのいずれかを表します。 |
オブジェクト |
|
適用されるターゲット条件のタイプ。 |
文字列 |
|
ルームのユニットIDを含むオブジェクトのリスト。ユニットIDは |
配列 |
|
ルームのユニットID。 |
文字列 |
|
キャンペーンのスケジュール情報。 |
オブジェクト |
|
キャンペーンがアクティブになる期間を指定するタイムウィンドウオブジェクト。 |
オブジェクト |
|
タイムウィンドウの開始時刻。ISO 8601形式(YYYY-MM-DDThh:mm:ssZ)に則ったRFC 3339プロファイルを使用する文字列です。 |
文字列 |
|
タイムウィンドウの終了時刻。ISO 8601形式(YYYY-MM-DDThh:mm:ssZ)に則ったRFC 3339プロファイルを使用する文字列です。 |
文字列 |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
200 |
OK |
リクエストが成功しました。 |
400 |
Bad Request |
リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
401 |
Unauthorized |
アクセストークンがないか、期限切れか、無効です。 |
403 |
Forbidden |
操作を実行する権限がユーザーにありません。 |
429 |
Too Many Requests |
リクエストが制限されています。 |
500 |
Internal Server Error |
内部サービスエラーのためリクエストを処理できませんでした。 |
503 |
Service Unavailable |
サービスが一時的に使用できません。 |
キャンペーンを取得する
作成したキャンペーンを取得します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
GET /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエスト本文の形式
なし。
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
取得するキャンペーンのID。この値は、キャンペーンを作成したときに返されます。 |
文字列 |
◯ |
成功応答のヘッダー
Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
◯ |
応答本文の形式
{
"campaignId": "campaignId",
"suggestion": {
"variants": [{
"placement": {
"channel": "HOME"
},
"content": {
"values": [{
"locale": "en-US",
"document": {},
"datasources": {}
}]
}
}]
},
"targeting": {
(タイプがユニットのポリモーフィックオブジェクト)
},
"scheduling": {
"activationWindow": {
"start": "2021-01-01T10:00:00.00Z",
"end": "2021-01-31T10:00:00.00Z"
}
},
"validationStatus": {
"value": "string enum", // IN_PROGRESS、APPROVED、REJECTED
"reason": "Explanation"
}
}
応答本文のパラメーター
フィールド | 説明 | 型 |
---|---|---|
キャンペーン情報 |
キャンペーンの作成時に指定した詳細。フィールドについては、キャンペーン作成時のリクエスト本文の形式を参照してください。 |
オブジェクト |
|
キャンペーンの検証ステータス。 |
オブジェクト |
|
キャンペーンの最新の検証ステータス。 |
オブジェクト |
|
キャンペーンの最新の検証ステータス。有効な値は |
文字列 |
|
検証ステータスの値の説明(該当する場合)。 |
文字列 |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
200 |
Successful |
リクエストが正常に処理されました。 |
400 |
Bad Request |
リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
401 |
Unauthorized |
アクセストークンがないか、期限切れか、無効です。 |
403 |
Forbidden |
アクセストークンは有効ですが、必要なLWAスコープの権限をユーザーが持っていません。 |
404 |
Not Found |
削除するキャンペーンが見つかりません。 |
429 |
Too Many Requests |
リクエストが制限されています。 |
500 |
Internal Server Error |
内部サービスエラーのためリクエストを処理できませんでした。 |
503 |
Service Unavailable |
サービスが一時的に使用できません。 |
キャンペーンを削除する
キャンペーンを削除します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本 |
米国 |
リクエストの形式
DELETE /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
削除するキャンペーンのID。この値は、キャンペーンを作成したときに返されます。 |
文字列 |
◯ |
リクエスト本文
なし。
成功応答ヘッダー
HTTP/1.1 202 OK
Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
◯ |
応答本文
なし。
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
202 |
Accepted |
指定されたキャンペーンに対する削除リクエストが受け付けられました。キャンペーンは削除されますが、サジェスチョンが配信済みでない保証はありません。 |
400 |
Bad Request |
リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
401 |
Unauthorized |
アクセストークンがないか、期限切れか、無効です。 |
403 |
Forbidden |
アクセストークンは有効ですが、必要なLWAスコープの権限をユーザーが持っていません。 |
404 |
Not Found |
削除するキャンペーンが見つかりません。 |
429 |
Too Many Requests |
リクエストが制限されています。 |
500 |
Internal Server Error |
内部サービスエラーのためリクエストを処理できませんでした。 |
キャンペーンテンプレート
以下のセクションでは、プロアクティブキャンペーンに使用できる各テンプレートについて詳しく説明します。テンプレートは、キャンペーンを作成するリクエスト本文のsuggestion.variants[].content.values[].document.src
プロパティに指定します。その後、テンプレートに応じたフィールドをsuggestion.variants[].content.values[].datasources
プロパティに設定します。
背景画像について
各テンプレートには、background.backgroundImageSource
プロパティを使用して背景画像を指定できます。テンプレートでは、画面全体に表示されるように画像のサイズが均一に拡大または縮小されます(「best-fill」)。つまり、画像のアスペクト比とデバイス画面のアスペクト比が一致しない場合は、画像が途切れる可能性があります。
画像を適切に表示するには、以下の推奨事項を検討してください。
- 画像の端までテキストがある画像は使用しないでください。画像のサイズ調整によって、テキストが切り詰められる可能性があります。
- 可能であれば、ユニットで使用されているものと同じタイプのデバイスで、画像をテストしてください。
- 別々のユニットに異なるデバイスが含まれている場合は、デバイスに合わせて画像を最適化できるように、異なるプロアクティブキャンペーンを使用して個々のユニットをターゲットにすることを検討してください。この方法は、同一のユニット内ですべてのデバイスのアスペクト比が同じである場合に有効です。
PNGまたはJPG形式の画像を指定できます。画像ファイルのサイズは400KB以内にする必要があります。
テキスト折り返し
テキスト折り返しテンプレート(doc://alexa/apl/documents/home/cards/textWrapping
)は、背景画像の上にテキストを表示します。このテンプレートでは、スキルを起動するボタンを含めることもできます。
このテンプレートのsuggestion.variants[].content.values[].datasources
オブジェクトには、以下のプロパティがあります。
プロパティ名 | 説明 | 型 | 必須 |
---|---|---|---|
|
表示するアトリビューション画像のURL。 |
文字列 |
✕ |
|
ほかのテキストフィールドの下に表示されるアトリビューションテキスト。 |
文字列 |
✕ |
|
背景画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。 |
文字列 |
✕ |
|
ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。 |
文字列 |
✕ |
|
画面下部に表示されるヒントテキスト。 |
文字列 |
✕ |
|
表示する第1テキスト。このテキストは、ほかのテキストよりも大きいフォントで表示されます。 |
文字列 |
◯ |
|
第1テキストの下に小さいフォントで表示される第2テキスト。 |
文字列 |
✕ |
|
第2テキストの横に表示される第3テキスト。 |
文字列 |
✕ |
|
|
ブール値 |
✕ |
|
設定すると、指定したラベルの付いたアクションボタンがテキストの下に表示されます。ユーザーがボタンをタップすると、指定した |
文字列 |
✕ |
|
ユーザーが再生ボタンまたはアクションボタンをタップしたときに実行するアクションを定義するオブジェクト。 |
オブジェクト |
◯ |
|
アクションのタイプ。 |
文字列 |
◯ |
|
カードに関連付けるスキルのURI。 例: |
文字列 |
◯ |
メディア
メディアテンプレート(doc://alexa/apl/documents/home/cards/media
)は、テキストの横に大きいサムネイル画像を表示します。
このテンプレートのsuggestion.variants[].content.values[].datasources
オブジェクトには、以下のプロパティがあります。
プロパティ名 | 説明 | 型 | 必須 |
---|---|---|---|
|
表示するアトリビューション画像のURL。 |
文字列 |
✕ |
|
ほかのテキストフィールドの下に表示されるアトリビューションテキスト。 |
文字列 |
✕ |
|
背景画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。 |
文字列 |
✕ |
|
ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。 |
文字列 |
✕ |
|
画面下部に表示されるヒントテキスト。 |
文字列 |
✕ |
|
表示する第1テキスト。このテキストは、ほかのテキストよりも大きいフォントで表示されます。 |
文字列 |
◯ |
|
第1テキストの下に小さいフォントで表示される第2テキスト。 |
文字列 |
✕ |
|
第2テキストの横に表示される第3テキスト。 |
文字列 |
✕ |
|
テキストフィールドの横に表示する画像のサムネイルのURL。 |
文字列 |
✕ |
レーティング
レーティングテンプレート(doc://alexa/apl/documents/home/cards/rating
)は、テキストを星評価と共に表示します。
このテンプレートのsuggestion.variants[].content.values[].datasources
オブジェクトには、以下のプロパティがあります。
プロパティ名 | 説明 | 型 | 必須 |
---|---|---|---|
|
背景画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。 |
文字列 |
✕ |
|
ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。 |
文字列 |
✕ |
|
画面下部に表示されるヒントテキスト。 |
文字列 |
✕ |
|
表示する第1テキスト。このテキストは、ほかのテキストよりも大きいフォントで表示されます。 |
文字列 |
◯ |
|
レーティングを表す星の数。レーティングの数値は1~5の範囲で指定でき、 |
1~5の数値 |
◯ |
|
星評価のコンテキストを表す短いテキスト。8文字未満にする必要があります。 |
文字列 |
◯ |
|
表示する画像のサムネイルのURL。 |
文字列 |
✕ |
あなたの1日
あなたの1日テンプレート(doc://alexa/apl/documents/home/cards/suggestedActions
)は、ヒントテキストとサムネイル画像から成る項目を3つまで表示します。ユーザーが項目をタップしたときに実行するアクションを定義できます。
このテンプレートで表示される項目の数は、デバイスのサイズによって異なります。たとえば、Echo Show 15では3つすべてが表示され、Echo Show 8では最初の2つが表示されます。Echo Show 5などの小型デバイスでは1つの項目だけが表示されます。
このテンプレートのsuggestion.variants[].content.values[].datasources
オブジェクトには、以下のプロパティがあります。
プロパティ名 | 説明 | 型 | 必須 |
---|---|---|---|
|
背景画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。 |
文字列 |
✕ |
|
ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。 |
文字列 |
✕ |
|
表示する最大3つのリスト項目オブジェクトの配列。 |
オブジェクトの配列 |
✕ |
|
項目に表示するテキスト。80文字以下にする必要があります。 |
文字列 |
✕ |
|
|
文字列 |
✕ |
|
ユーザーがリスト項目のいずれかをタップしたときに実行するアクションを定義するオブジェクト。すべてのリスト項目で使用される単一のアクションを定義できます。 |
オブジェクト |
◯ |
|
アクションのタイプ。 |
文字列 |
◯ |
|
カードに関連付けるスキルのURI。 例: |
文字列 |
◯ |
|
スキルに渡すデータ。この機能はサポートされていないため、このプロパティは空のオブジェクト |
オブジェクト |
◯ |
この日
この日テンプレート(doc://alexa/apl/documents/home/cards/primePhoto
)は、写真と短いテキストを全画面に表示します。
このテンプレートのsuggestion.variants[].content.values[].datasources
オブジェクトには、以下のプロパティがあります。
プロパティ名 | 説明 | 型 | 必須 |
---|---|---|---|
|
表示する画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。 |
文字列 |
✕ |
|
ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。 |
文字列 |
✕ |
|
画面下部に表示されるヒントテキスト。 |
文字列 |
✕ |
|
ヘッダーの後に表示する第1テキスト。 |
文字列 |
◯ |
|
ユーザーが画面上の任意の場所をタップしたときに実行するアクションを定義するオブジェクト。 |
オブジェクト |
◯ |
|
アクションのタイプ。 |
文字列 |
◯ |
|
カードに関連付けるスキルのURI。 例: |
文字列 |
◯ |
|
スキルに渡すデータ。この機能はサポートされていないため、このプロパティは空のオブジェクト |
オブジェクト |
◯ |
写真カード
写真カードテンプレート(doc://alexa/apl/documents/home/cards/selectedPhoto
)は、写真と短い第1テキストおよび第2テキストを全画面に表示します。
このテンプレートのsuggestion.variants[].content.values[].datasources
オブジェクトには、以下のプロパティがあります。
プロパティ名 | 説明 | 型 | 必須 |
---|---|---|---|
|
表示する画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。 |
文字列 |
✕ |
|
画面下部に表示されるヒントテキスト。 |
文字列 |
✕ |
|
表示する第1テキスト。やや大きいフォントで表示されます。 |
文字列 |
◯ |
|
第1テキストの下に表示する第2テキスト。 |
文字列 |
◯ |
|
ユーザーが画面上の任意の場所をタップしたときに実行するアクションを定義するオブジェクト。 |
オブジェクト |
◯ |
|
アクションのタイプ。 |
文字列 |
◯ |
|
カードに関連付けるスキルのURI。 例: |
文字列 |
◯ |
|
スキルに渡すデータ。この機能はサポートされていないため、このプロパティは空のオブジェクト |
オブジェクト |
◯ |
関連トピック
最終更新日: 2024 年 06 月 19 日