Filtering and Personalization
Defining audiences in a map or for a deployment enables your content to reach the recipients you intend for it. This way users receive the information that is relevant to them, and are restricted from accessing other content.
Define Audiences in a Map
Heretto Deploy API enables you to filter content by associating DITAVALs with maps and by using tokens.
- Insert the data element into the sitemap:
<data name="content-api-audience" value="audience_name" href="ditaval_path"/> - Optional: To profile a map for multiple audiences, add multiple data elements to a map.
| Value | Description | Example |
|---|---|---|
| audience_name | The name of the audience. This name is used during Single Sign-On and can be used for the JSON Web Token (JWT) authentication. See Link Variables. | audience_a |
| ditaval_path | The path to the DITAVAL file. | ditavals/audience_a.ditaval |
Define Audiences in Deployments
You can define audiences for entire deployments in the Heretto user interface.
- In the top-left corner, click the Main Menu
and go to Deployments.
- In the interface:
- Click New Deployment.
- Click the name of an existing deployment, then in the next window, click Edit deployment.
- Click Add audience.
- Name the audience.
- Click Add file and select a DITAVAL file from the Content Library.
- Optional: If you want an audience to be the default audience for a deployment, select Default.
- Save.
Define Parameters with Tokens
When you use a DITAVAL to define a map, a JSON Web Token (JWT) passes the parameter values to filter the content based on authentication.
The JWT passes the DITAVAL information added to a link as a parameter. The token parameter supports every Deploy API endpoint. For more information about JWTs, see Authentication and Security.
The following example shows a link to unfiltered content. The link does not include the audience parameter.
web_asset_address/sitemap_path/endpoint?token=JWT
The following example shows a link to filtered content. The link includes the audience parameter.
web_asset_address/sitemap_path/endpoint?token=JWT&audience=audience_name
| Variable | Description | Example |
|---|---|---|
| web_asset_address | Your website or web application address. | https://www.yourorganization.com |
| sitemap_path | The path to the sitemap UUID that you profile for different audiences. | guides/installation-guide/b24a39d0-e564-11e9-a84f-0242d5a6215b |
| endpoint | An endpoint of your choice. | See API Endpoint Specification. |
| JWT | The JWT. | 02b2mf12ak033850fg222n502gb01503&full=true |
| audience_name | The audience name matching the @value attribute value of the DITAVAL data element. | audience_a |