Clank HaTS Survey Integration Guide

This one-page explains the integration steps needed to use HaTS on Clank. For generic integration flow beyond coding, please see go/clank-hats.

1 - Add SurveyConfig

Define your SurveyConfig in survey_config.h, and fill in the details in survey_config.cc.

This is also the time to decide the requirements for the survey (e.g. is the survey user-prompt? What PSD will be attached to the survey?). The survey_configs are owned by privacy reviewers - when adding a new SurveyConfig, please be sure to get reviews from one of the OWNERS in //chrome/browser/ui/hats/OWNERS.

2 - Create SurveyUiDelegate

Create a SurveyUiDelegate instance that is used to display the survey. This is needed in order to create a SurveyClient (see below).

Java client

There is a ready-to-use MessageSurveyUiDelegate that shows the invitation using a Clank message; features can implement the interface SurveyUiDelegate to define their own behaviors.

C++ client

The survey UI interface is defined in hats::SurveyUiDelegateAndroid. The interface allows users to create a message UI client, or implement their own behaviors.

3 - Create SurveyClient

Create a SurveyClient instance. Once the client instance is ready, use showSurvey() to start the survey presentation flow.

showSurvey() is also the chance to pass in the PSD when showing the survey. This means features don’t have to always have the PSD ready when creating the SurveyClient. In order for the PSD to link correctly, the number of keys and values for the PSD has to match exactly what’s defined in the survey_config.cc.

Java client

Use SurveyClientFactory.getInstance().createClient() to create an instance.

C++ client

Use hats::HatsServiceAndroid to launch the new survey.

Reference

Example usage

Survey presentation flow

App or feature (ChromeSurveyController in this example) code calls SurveyFactory.createSurveyClient() to create a SurveyClient, possibly with a SurveyUiDelegate (MessagesSurveyUiDelegate in this example)

  1. App or feature call SurveyClient.showSurvey() to start downloading in the background;
  2. A throttling check canShowSurvey() will be performed; downloadSurvey() will start if the throttler check is passed; SurveyClient will communicate with SurveyController that eventually calls HaTS client API;
  3. Once survey download is completed, SurveyUiDelegate.showSurveyInvitation() is called to present the survey.
    • Internally, SurveyClient calls showSurveyInvitation()
    • If the download is not completed yet or failed, showSurveyInvitation() will not be called.
  4. Once Survey is shown, SurveyClient.destroy() to release objects.

(More design / implementation details see design doc: go/clank-hats-2023)