| Wenyu Fu | 50d3c9f | 2024-12-27 18:46:01 | [diff] [blame] | 1 | # Clank HaTS Survey Integration Guide |
| 2 | |
| 3 | This one-page explains the integration steps needed to use HaTS on Clank. For generic integration flow beyond coding, please see [go/clank-hats](go/clank-hats). |
| 4 | |
| 5 | [TOC] |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## 1 - Add SurveyConfig |
| 10 | |
| 11 | Define your SurveyConfig in `survey_config.h`, and fill in the details in `survey_config.cc`. |
| 12 | |
| 13 | 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`. |
| 14 | |
| 15 | |
| 16 | ## 2 - Create SurveyUiDelegate |
| 17 | |
| 18 | Create a [SurveyUiDelegate](java/src/org/chromium/chrome/browser/ui/hats/SurveyUiDelegate.java) instance that is used to display the survey. This is needed in order to create a SurveyClient (see below). |
| 19 | |
| 20 | ### Java client |
| 21 | There is a ready-to-use [MessageSurveyUiDelegate](java/src/org/chromium/chrome/browser/ui/hats/MessageSurveyUiDelegate.java) that shows the invitation using a Clank message; features can implement the interface `SurveyUiDelegate` to define their own behaviors. |
| 22 | |
| 23 | ### C++ client |
| 24 | The survey UI interface is defined in [hats::SurveyUiDelegateAndroid](https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/ui/android/hats/survey_ui_delegate_android.h;l=32?q=hats::SurveyUiDelegateAndroid&ss=chromium%2Fchromium%2Fsrc). The interface allows users to create a message UI client, or implement their own behaviors. |
| 25 | |
| 26 | ## 3 - Create SurveyClient |
| 27 | Create a `SurveyClient` instance. Once the client instance is ready, use `showSurvey()` to start the survey presentation flow. |
| 28 | |
| 29 | `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`. |
| 30 | |
| 31 | ### Java client |
| 32 | Use [SurveyClientFactory.getInstance().createClient()](https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/ui/android/hats/internal/java/src/org/chromium/chrome/browser/ui/hats/SurveyClientFactory.java;l=79?q=SurveyClientFactory.createClient&sq=&ss=chromium%2Fchromium%2Fsrc) to create an instance. |
| 33 | |
| 34 | |
| 35 | ### C++ client |
| 36 | Use [hats::HatsServiceAndroid](https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/ui/android/hats/hats_service_android.h;l=36?q=HatsServiceAndroid&ss=chromium%2Fchromium%2Fsrc) to launch the new survey. |
| 37 | |
| 38 | ## Reference |
| 39 | |
| 40 | |
| 41 | ### Example usage |
| 42 | * Java client: [ChromeSurveyControlle](https://source.chromium.org/chromium/chromium/src/+/main:chrome/android/java/src/org/chromium/chrome/browser/survey/ChromeSurveyController.java) |
| 43 | * C++ client: [ChromePermissionsClient::TriggerPromptHatsSurveyIfEnabled](https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/permissions/chrome_permissions_client.cc;l=281?q=ChromePermissionsClient::TriggerPromptHatsSurveyIfEnabled&ss=chromium%2Fchromium%2Fsrc) |
| 44 | |
| 45 | ### Survey presentation flow |
| 46 | |
| 47 | App or feature (`ChromeSurveyController` in this example) code calls `SurveyFactory.createSurveyClient()` to create a SurveyClient, possibly with a `SurveyUiDelegate` (`MessagesSurveyUiDelegate` in this example) |
| 48 | |
| 49 | 1. App or feature call `SurveyClient.showSurvey()` to start downloading in the background; |
| 50 | 2. A throttling check `canShowSurvey()` will be performed; |
| 51 | `downloadSurvey()` will start if the throttler check is passed; SurveyClient will communicate with `SurveyController` that eventually calls HaTS client API; |
| 52 | 3. Once survey download is completed, `SurveyUiDelegate.showSurveyInvitation()` is called to present the survey. |
| 53 | * Internally, SurveyClient calls showSurveyInvitation() |
| 54 | * If the download is not completed yet or failed, showSurveyInvitation() will not be called. |
| 55 | 4. Once Survey is shown, `SurveyClient.destroy()` to release objects. |
| 56 | |
| 57 | (More design / implementation details see design doc: [go/clank-hats-2023](go/clank-hats-2023)) |
