Deploy API Filtering and Personalization
Audience-based filtering applies only to JSON Web Token (JWT) authentication. Simple API Keys cannot be restricted to specific audiences and always have full access to content across all audiences within their configured scope.
Audience-based filtering and personalization let a single map or deployment return different content to different groups of users, so each request receives only the content meant for its audience.
An audience identifies a group of intended recipients for a portion of your content. You associate content with an audience by adding a content-api-audience or content-api-default-audience data element to the main portal sitemap, pointing to a DITAVAL, or by defining named audiences for a deployment.
There are two places to define an audience, and they differ in scope:
Audiences defined in a map: They associate a single sitemap with one or more DITAVAL files, each representing a different audience. See Define Audiences in a Map.
Audiences defined in a deployment: They apply across an entire deployment and let you designate one audience as the default for the deployment. See Define Audiences in Deployments.
To retrieve content for a specific audience, add the audience parameter to a request URL, for example, ?audience=private. For details on how to create such a request, see Define Parameters with Tokens. To learn how the requested audience interacts with the audiences claim in a JWT, see Deploy API Authentication.
Define Audiences in a Map
Associate a map with an audience so its content is returned only to JWT-authenticated requests permitted for that audience.
This assigns an audience at the map level. To assign an audience to an entire deployment instead, see Define Audiences in Deployments. The audience name you assign here is the value you'll reference later when configuring the audiences claim in a JWT (see Deploy API Authentication) or the audience request parameter (see Define Parameters with Tokens).
Every JWT request is matched to an audience. Here is a breakdown of possible scenarios.
-
A specific audience is used when:
-
content-api-audienceis used in thedataelement in your sitemap, and a value is specified. Example:<data href="../filters/private.ditaval" name="content-api-audience" value="private"/>
-
-
Audience is mapped to the
__defaultvalue when:-
content-api-audienceis used in thedataelement in your sitemap, and no value is specified. Example:<data href="../filters/private.ditaval" name="content-api-audience" value=""/> -
content-api-default-audienceis used in thedataelement in your sitemap, regardless of whether a value is specified. Examples:<data href="filter/public_only_filter.ditaval" name="content-api-default-audience" value=""/><data href="filter/public_only_filter.ditaval" name="content-api-default-audience" value="general-audience"/> -
No audience is specified in a sitemap. In this case, no
dataelement pointing to a DITAVAL is present in the sitemap.
-
__default or a named audience. Once this deployment uses JWT authentication, requests permitted for that audience can access the content in this map, subject to the audiences claim in the requesting JWT.To configure Heretto Deploy API authentication with a Simple API Key or JSON Web Token (JWT), see Deploy API Authentication.
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.
- Click Save.
Define Parameters with Tokens
Add the audience parameter to a Heretto Deploy API request URL to specify which audience the returned content belongs to.
The audience parameter has an effect only on maps whose content has been associated with an audience via a DITAVAL, as described in Define Audiences in a Map and Define Audiences in Deployments. Add it to the link alongside the token used for authentication. The token parameter supports every Deploy API endpoint. For more information about how the audience parameter interacts with the audiences claim in a JSON Web Token (JWT), see Deploy API Authentication.
This example shows a link to unfiltered content, using the content endpoint. The link does not include the audience parameter.
https://{organizationId}.deploy.heretto.com/v4/deployments/{deploymentIdentifier}/content?for-path={path}&token={JWT}audience parameter. The audience parameter applies only to requests authenticated with a JWT.
https://{organizationId}.deploy.heretto.com/v4/deployments/{deploymentIdentifier}/content?for-path={path}&token={JWT}&audience={audience_name}Where:
{organizationId} is the identifier for your organization. See Obtain Parameter Values for Endpoint URLs.
{deploymentIdentifier} is the identifier for the deployment you're calling. See Obtain Parameter Values for Endpoint URLs.
{endpoint} is an endpoint of your choice, such as
content(shown above) orstructure. See Deploy API Endpoint Specification at Heretto Deploy API.{path} is the
hrefvalue returned by the structure endpoint, for the content you want to retrieve.{JWT} is the signed JSON Web Token (JWT) used to authenticate the request. See Create a JWT.
{audience_name} is the audience name set in the
valueattribute of acontent-api-audiencedata element in the sitemap. See Define Audiences in a Map.