会話のデータを保存する

ある特定の会話のターンの間またはいくつかの会話にわたって状態を保存する必要がある場合は、AppResponse オブジェクトの conversationToken フィールドまたは userStorage フィールドを使用します。

conversationToken フィールドは、会話のターンが変わるたびにアクションに再循環される不透明トークンを含む文字列です。たとえば、会話の最初のターンの AppResponse でこのフィールドの値を "count=1" に設定した場合、会話の 2 回目のターンでアクションが受け取った AppRequestconversationToken"count=1" が含まれます。このトークンは、会話の始めに必ず空の文字列に初期化されます。Actions on Google Node.js クライアント ライブラリを使用する場合は、conv.dataconvConversation のインスタンス)を使用して会話トークンを JSON オブジェクトとしてやり取りできます。

userStorage フィールドは、アクションによって提供され、特定のユーザーの会話にわたって保存される不透明トークンを含む文字列です。たとえば、ユーザーが獲得したゲームの最高スコアを userStorage に保存しておき、ユーザーが新しい会話を開始するたびにウェルカム メッセージでその値を使用できます。Actions on Google Node.js クライアント ライブラリを使用する場合は、conv.user.storageconvConversation のインスタンス)を使用してユーザー ストレージを JSON オブジェクトとしてやり取りできます。

会話のターンの間でデータを保存する

次のサンプルは、AppResponse の会話トークンにカウンタを保存する方法を示します。

Node.js
function simpleResponse(conv) {
  conv.data.count = 1;
  conv.ask('Hi there, what can I help you with today?');
}
Java
public ActionResponse simpleResponseAppData(ActionRequest request) {
  ResponseBuilder responseBuilder = getResponseBuilder(request);
  Map<String, Object> data = request.getConversationData();
  data.put("count", 1);
  return responseBuilder
      .add("Hi there, what can I help you with today?")
      .build();
}
Dialogflow JSON
{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Hi there, what can I help you with today?"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}"
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{\"count\":1}"
      }
    }
  ]
}
Actions SDK JSON
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Hi there, what can I help you with today?"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{\"count\":1}}",
  "userStorage": "{\"data\":{}}"
}

実用的な使用例については、有用な再プロンプトを提供して適切に失敗するベスト プラクティス ガイドをご覧ください。

複数の会話にわたってデータを保存する

次のサンプルは、AppResponse のユーザー ストレージにカウンタを保存する方法を示します。

Node.js
function simpleResponse(conv) {
  conv.user.storage.count = 1;
  conv.ask('When is your birthday?');
}
Java
public ActionResponse simpleResponseUserStorage(ActionRequest request) {
  ResponseBuilder responseBuilder = getResponseBuilder(request);
  Map<String, Object> userStorage = request.getUserStorage();
  userStorage.put("count", 1);
  return responseBuilder
      .add("When is your birthday?")
      .build();
}
Dialogflow JSON
{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "When is your birthday?"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{\"count\":1}}"
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{}"
      }
    }
  ]
}
Actions SDK JSON
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "When is your birthday?"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{\"count\":1}}"
}

実用的な使用例については、ユーザー設定を使用して会話をカスタマイズするベスト プラクティス ガイドをご覧ください。

法的注意事項: userStorage にアクセスする前に同意を得てください。一部の国では、デベロッパーが userStorage にアクセスする前、または特定の情報(個人情報など)を保存する前にユーザーから同意を得ることを義務付ける規制があります。そのような国で事業を展開している場合に、userStorage にアクセスするとき、または該当する情報を保存するときは、確認ヘルパーを使用してユーザーに同意を求め、同意を得てからその情報を userStorage に保存する必要があります。

ユーザー ストレージの有効期限

アシスタントが ID のマッチングによってユーザーを特定できる場合、ユーザー ストレージの内容は期限切れになりません。この場合、ユーザー ストレージの内容をクリアできるのはユーザーまたはアクション自体だけです。

アシスタントが ID のマッチングによってユーザーを特定できない場合、ユーザー ストレージの内容は会話の終了時にクリアされます。たとえば次のような場合、アシスタントは ID からユーザーを特定できません。

  • Voice Match が設定されていて、一致する音声が見つからない。
  • ユーザーが個人データを無効にした。

userStorage フィールドの内容をクリアする

アクションの userStorage フィールドの内容をクリアするには、AppResponseresetUserStorage フィールドを true に設定します。userStorage の値を空の文字列に設定した場合、会話の次のターンでは元の userStorage の値が送られます。そのため、内容が変更された場合を除き、受け取った userStorage 全体を送信し戻す必要はありません。

Actions on Google Node.js クライアント ライブラリを使用する場合は、conv.user.storage の値を {}(空のオブジェクト)に設定するだけで済みます。

Node.js
function simpleResponse(conv) {
  conv.user.storage = {};
  conv.ask('Okay, I cleared your data');
}
Java
public ActionResponse simpleResponseUserStorage2(ActionRequest request) {
  ResponseBuilder responseBuilder = getResponseBuilder(request);
  // Resets the user storage.
  request.getUserStorage().clear();

  return responseBuilder
      .add("Okay, I cleared your data")
      .build();
}
Dialogflow JSON
{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Okay, I cleared your data"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}"
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{}"
      }
    }
  ]
}
Actions SDK JSON
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Okay, I cleared your data"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{}}"
}

ユーザーは、呼び出したアクションのユーザー ストレージ フィールドの内容を表示できます。また、サービスが自分の情報を保存することを許可しないように設定することで、その特定のアクションから保存されているユーザーデータを削除することもできます。

  1. スマートフォンでアシスタント アプリを開きます。
  2. 引き出しのアイコンをクリックします。

  3. [使い方・ヒント] タブで、ユーザー ストレージを表示またはクリアする対象のアクションを探し、タップして詳細ページを開きます。
  4. ページの一番下までスクロールします。
    • ユーザー ストレージ フィールドの内容を表示するには、[View stored data](保存済みデータを表示)をタップします。
    • 保存されているユーザーデータを削除するには、[Stop $action from remembering me]($action に自分の情報を保存することを許可しない)をタップします。