会話のデータを保存する(Dialogflow)

Dialogflow で調べる

[続行] をクリックして、Dialogflow に保存済みデータのサンプルをインポートします。次に、以下の手順に沿ってサンプルをデプロイしてテストします。

  1. エージェント名を入力し、サンプル用に新しい Dialogflow エージェントを作成します。
  2. エージェントのインポートが完了したら、[Go to agent] をクリックします。
  3. メインのナビゲーション メニューから [Fulfillment] に移動します。
  4. [インライン エディタ] を有効にして、[デプロイ] をクリックします。エディタにはサンプルコードが含まれています。
  5. メインのナビゲーション メニューから [Integrations] に移動し、[Google Assistant] をクリックします。
  6. 表示されたモーダル ウィンドウで [変更の自動プレビュー] を有効にし、[Test] をクリックして Actions シミュレータを開きます。
  7. シミュレータで「Talk to my test app」と入力してサンプルをテストします。
続行

多くの場合、会話のターン間で、またはユーザーとの複数の会話にわたってデータを保存すると、優れたユーザー エクスペリエンスを実現できます。これは、1 つの会話で有用な再プロンプトを提供する場合、セッションをまたいでゲームスコアを保存する場合、またはユーザーに関する少量の情報を記憶する場合に役立ちます。

その要件は、データを保存する必要がある会話内か会話をまたいで保存する必要があるかによって若干異なります。会話のデータを保存するには、AppResponse オブジェクトの conversationToken フィールドを使用します。

複数の会話にわたってデータを保存するには、次の手順に従います。

  1. ユーザーが確認済みか、またはゲストであるかを判断します。
  2. AppResponse オブジェクトの userStorage フィールドを使用して、ユーザーデータの保存またはアクセスを行います。

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

conversationToken フィールドは、会話のターンごとにアクションに再循環される不透明なトークンを含む文字列です。たとえば、最初の会話の AppResponse で値を "count=1" に設定した場合、会話の 2 回目のターンでアクションが受け取る AppRequestconversationToken には "count=1" が含まれます。

トークンは、会話の開始時に常に空の文字列で初期化されます。Actions on Google Node.js クライアント ライブラリを使用する場合は、conv.data を使用して、会話トークンを JSON オブジェクトとしてやり取りできます。ここで、convConversation のインスタンスです。

次のサンプルは、AppResponseconversationToken フィールドにカウンタを保存する方法を示しています。

Node.js

conv.data.firstNum = firstNum;
conv.ask(`Got it, the first number is ${firstNum}.`);
conv.ask(`What's the second number?`);

Java

ResponseBuilder responseBuilder = getResponseBuilder(request);
responseBuilder.getConversationData().put("firstNum", firstNum);
responseBuilder.add("Got it, the first number is " + firstNum + ".");
responseBuilder.add("What's the second number?");
return responseBuilder.build();

JSON

以下の JSON は、conversationToken ではなく outputContexts を使用する Webhook レスポンスを記述しています。

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Got it, the first number is 23."
            }
          },
          {
            "simpleResponse": {
              "textToSpeech": "What's the second number?"
            }
          }
        ]
      }
    }
  },
  "outputContexts": [
    {
      "name": "projects/save-data-df-js/agent/sessions/ABwppHGfFkWJdHKPpBEYiGkhdoakWmYj_2sZa4o8pbGG9nj4q5_GfDTtNEXOY34mLX8G4o_d7oZdUW9bnBZC/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{\"firstNum\":23}"
      }
    }
  ]
}

JSON

下記の JSON は Webhook レスポンスを示します。

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Got it, the first number is 23."
              }
            },
            {
              "simpleResponse": {
                "textToSpeech": "What's the second number?"
              }
            }
          ]
        }
      }
    }
  ],
  "conversationToken": "{\"data\":{\"firstNum\":23}}"
}

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

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

AppResponse オブジェクトの userStorage フィールドは、アクションによって提供される不透明トークンを含む文字列です。このトークンは、特定のユーザーの会話全体に保存されます。たとえば、ユーザーの最高スコアを userStorage に保存し、ユーザーが新しい会話を開始するたびにウェルカム メッセージでその値を使用できます。

ユーザー確認ステータスの判別と処理

ユーザーの確認ステータスの値は GUEST または VERIFIED のいずれかです。各会話の開始時に、Actions on Google は会話開始時のさまざまなインジケーターに基づいてユーザーの確認ステータスを設定します。一例として、モバイル デバイスで Google アシスタントにログインしたユーザーの確認ステータスは VERIFIED です。

ユーザーの確認ステータスが GUEST の場合、次のような理由が考えられます。

  • ユーザーがアカウントに基づく情報を無効にしている。
  • ユーザーが各自のウェブとアプリのアクティビティを無効にしている。ユーザーによっては、この設定をドメインレベルで無効にしている場合があります。
  • デバイスで Voice Match が有効である場合に、一致しないかまたはユーザーが自分の声を使わずに(Google Home の長押しなどを使って)アシスタントを呼び出す。
  • ユーザーがログインしていない。

userStorage でデータを保存する前、またはアカウントのリンクフローを開始する前に、必ずユーザーの確認ステータスを確認して、ゲストユーザーがエラーとなる機能を操作できないようにしてください。

Node.js 用 Actions On Google クライアント ライブラリを使用する場合は、conv.user.storage を使用してユーザー ストレージを JSON オブジェクトとして操作できます。ここで、convConversation のインスタンスです。次のサンプルは、AppResponseuserStorage フィールドにカウンタを保存する方法を示しています。

Node.js

app.intent('Save Sum', (conv) => {
  if (conv.user.verification === 'VERIFIED') {
    conv.user.storage.sum = conv.data.sum;
    conv.close(`Alright, I'll store that for next time. See you then.`);
  } else {
    conv.close(`I can't save that right now, but we can add ` +
      `new numbers next time!`);
  }
});

Java

@ForIntent("Save Sum")
public ActionResponse saveSum(ActionRequest request) {
  ResponseBuilder responseBuilder = getResponseBuilder(request);
  Integer sum = ((Double) request.getConversationData().get("sum")).intValue();
  String verificationStatus = request.getUser().getUserVerificationStatus();
  if (verificationStatus.equals("VERIFIED")) {
    responseBuilder.getUserStorage().put("sum", sum);
    responseBuilder.add("Alright, I'll store that for next time. See you then.");
  } else {
    responseBuilder.add("I can't save that right now, but we can add new numbers next time!");
  }
  responseBuilder.endConversation();
  return responseBuilder.build();
}

Node.js

if (conv.user.verification === 'VERIFIED') {
  conv.user.storage.sum = conv.data.sum;
  conv.close(`Alright, I'll store that for next time. See you then.`);
} else {
  conv.close(`I can't save that right now, but we can add ` +
    `new numbers next time!`);
}

Java

ResponseBuilder responseBuilder = getResponseBuilder(request);
Integer sum = ((Double) request.getConversationData().get("sum")).intValue();
String verificationStatus = request.getUser().getUserVerificationStatus();
if (verificationStatus.equals("VERIFIED")) {
  responseBuilder.getUserStorage().put("sum", sum);
  responseBuilder.add("Alright, I'll store that for next time. See you then.");
} else {
  responseBuilder.add("I can't save that right now, but we can add new numbers next time!");
}
responseBuilder.endConversation();
return responseBuilder.build();

JSON

下記の JSON は Webhook レスポンスを示します。

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Alright, I'll store that for next time. See you then."
            }
          }
        ]
      },
      "userStorage": "{\"data\":{\"sum\":68}}"
    }
  }
}

JSON

下記の JSON は Webhook レスポンスを示します。

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Alright, I'll store that for next time. See you then."
          }
        }
      ]
    }
  },
  "conversationToken": "{\"data\":{\"firstNum\":23,\"sum\":68}}",
  "userStorage": "{\"data\":{\"sum\":68}}"
}

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

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

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

アシスタントが ID とユーザーを照合できる場合、userStorage の内容は期限切れにならないため、ユーザーまたはアクション自体のみがクリアできます。

アシスタントが ID を照合できない場合、userStorage の内容は会話の終了時にクリアされます。以下に、アシスタントが ID とユーザーをマッチングできないケースの例を示します。

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

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

AppResponseresetUserStorage フィールドを true に設定すると、アクションの userStorage フィールドの内容を消去できます。userStorage の値を空の文字列に設定した場合、会話の次のターンで userStorage の値は変更されません。これにより、内容が変更されていない順番に userStorage 全体を送り返すことを回避できます。

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

Node.js

app.intent('Forget Number', (conv) => {
  conv.user.storage = {};
  conv.ask(`Alright, I forgot your last result.`);
  conv.ask(`Let's add two new numbers. What is the first number?`);
});

Java

@ForIntent("Forget Number")
public ActionResponse forgetNumber(ActionRequest request) {
  ResponseBuilder responseBuilder = getResponseBuilder(request);
  responseBuilder.getUserStorage().clear();
  responseBuilder.add("Alright, I forgot your last result.");
  responseBuilder.add("Let's add two new numbers. What is the first number?");
  return responseBuilder.build();
}

Node.js

conv.user.storage = {};
conv.ask(`Alright, I forgot your last result.`);
conv.ask(`Let's add two new numbers. What is the first number?`);

Java

ResponseBuilder responseBuilder = getResponseBuilder(request);
responseBuilder.getUserStorage().clear();
responseBuilder.add("Alright, I forgot your last result.");
responseBuilder.add("Let's add two new numbers. What is the first number?");
return responseBuilder.build();

JSON

下記の JSON は Webhook レスポンスを示します。

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Alright, I forgot your last result."
            }
          },
          {
            "simpleResponse": {
              "textToSpeech": "Let's add two new numbers. What is the first number?"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}"
    }
  }
}

JSON

下記の JSON は Webhook レスポンスを示します。

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Alright, I forgot your last result."
              }
            },
            {
              "simpleResponse": {
                "textToSpeech": "Let's add two new numbers. What is the first number?"
              }
            }
          ]
        }
      }
    }
  ],
  "userStorage": "{\"data\":{}}"
}

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

  1. スマートフォンでアシスタント アプリを開きます。
  2. ドロワー アイコンをタップします。

  3. [使い方・ヒント] タブで、ユーザー ストレージを表示またはクリアする対象のアクションを探し、タップして詳細ページを開きます。
  4. ページの一番下までスクロールします。
    • userStorage フィールドの内容を表示するには、[保存データを表示] をタップします。
    • 保存されているユーザーデータを削除するには、[$action によるユーザー情報の保存を停止] をタップします。