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 sitemap 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 data element with content-api-audience or content-api-default-audience attribute value 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 sitemap
Associate a single sitemap with one or more DITAVAL files, each representing a different audience. See Define Audiences in a Sitemap.
- Audiences defined in a deployment
Apply across an entire deployment and let you designate one audience as the default for the deployment. See Define Audiences in a Deployment.
Audiences can be configured in a sitemap, a deployment, or both. When both are configured, deployment audiences override sitemap audiences. Sitemap audiences are only used when no audiences are configured in the deployment.
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 Sitemap
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 a Deployment. 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.
-
Audience is mapped to the
__defaultvalue when:-
content-api-audienceis used in thedataelement in your main portal sitemap, and novalueattribute is specified. Example:<data href="../filters/private.ditaval" name="content-api-audience" value=""/> -
content-api-default-audienceis used in thedataelement in your main portal sitemap, regardless of whether thevalueattribute 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 your main portal sitemap. In this case, no
dataelement pointing to a DITAVAL is present in the sitemap.
-
-
A specific audience is used when:
-
content-api-audienceis used in thedataelement in your main portal sitemap, and thevalueattribute is specified. Example:<data href="../filters/private.ditaval" name="content-api-audience" value="private"/>
-
__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.Audiences can be configured in a sitemap, a deployment, or both. When both are configured, deployment audiences override sitemap audiences. Sitemap audiences are only used when no audiences are configured in the deployment.
To configure Heretto Deploy API authentication with a Simple API Key or JSON Web Token (JWT), see Deploy API Authentication.
Define Audiences in a Deployment
This procedure explains how to configure a deployment. Configuring audiences in a deployment is a part of this process.
You can define audiences for entire deployments in Heretto CCMS. Deployments connect content in the CCMS with Heretto Portal environments or other delivery endpoints via Heretto Deploy API and enable you to publish content to the associated delivery endpoint. A portion of this configuration must be completed by the Heretto team.
To complete this procedure, you must be assigned the Administrator role in Heretto CCMS.
Once the Heretto team completes the configuration on their side, the configuration of the deployment is complete. Users assigned the Administrator role in the CCMS can modify most aspects of the deployment with the exception of the sitemap it uses. To use a different sitemap in a deployment, a new deployment must be configured.
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 Sitemap and Define Audiences in a Deployment. 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 Sitemap.