How to use SDKs and APIs for Bookmarks

What are Bookmarks?

Bookmarks are part of Audience Insights that enable users to easily bookmark and save content for later. Bookmarks are directly tied to content via the ANS ID, ensuring precise tracking and retrieval.

It can also be implemented as standard PageBuilder Theme blocks to deliver a lightweight save-for-later experience.

Note

Bookmarks have a TTL of 60 days, meaning that any bookmarks older than 60 days will be automatically deleted from the system.

How can I implement Bookmarks on my site?

We provide a set of APIs and SDK methods that allow you to connect your end users with our system. To interact with our system, you can either call the APIs directly or use our SDK packages. Our SDK methods act as wrappers that help developers interact with our APIs more easily. We strongly recommend using our SDKs, as these libraries handle various tasks for you.

We also publish example code in our GitHub repository to help you get started quickly. For more information, see https://github.com/arcxp/audience-insights-examples.

Authentication and Authorization

For tracking user calls and accessing protected public APIs, most of our public APIs requires an access token. This access token is in JWT (JSON web tokens) format and is returned after the user is logged in to the system. See here for more: Connect and log in with Arc XP Identity SDKs and APIs on the web When the user logs in, two JWTs are returned if the request is successful:

• Access token: This token has a limited lifetime (15 minutes by default) and identifies the user. It must be passed as a Bearer token in the protected request.

• Refresh token: This token is used to refresh and obtain a new access token when the old one expires. You can customize the lifetime of the refresh token through the CSR tool.

You must pass the access token in the Authorization header as a Bearer token when making API calls that require authentication. It is recommended that you use the browser SDKs when possible, as they will handle token expiration and refreshing automatically.

Using Bookmarks on your site with the Audience Insights SDK

You must first have read access to the @arcxp Github Package repository. If your Github account does not have read access to the Github Packages under the @arcxp Github org, reach out to your TAM. Add your Github developer token to your .npmrc file, then install the package to your React project.

The Arc XP Audience Insights SDK is published to github packages. https://github.com/arcxp/arc-commerce-sdks/pkgs/npm/sdk-audience-insights

After you install npm, to install the Arc SDKs, execute the following command in your npm project:

npm install @arcxp/sdk-audience-insights

After you have them installed, include the SDKs in your code:

import AudienceInsights from '@arcxp/sdk-audience-insights';

To access the right API endpoints through the SDKs, specify an API Origin before calling any other SDK methods. You will need to pass Identity when initializing Audience Insights, as several methods require authentication, and the authentication is handled by Identity.

import Identity from '@arc-publishing/sdk-identity';

For more information and example code on how to implement Bookmarks refer to Bookmarks recipe in https://github.com/arcxp/audience-insights-examples.

Note

If you are using Page Builder, you can set up the API origin directly on the code (blocks.json file) or through the Page Builder app (Site Properties tab). Check How-to: ArcXP Identity Themes Blocks Configuration & Customization Deep Dive for additional information.

Using Bookmarks on your site or app with the public APIs

All available public APIs are documented in our Audience Insights OpenAPI documentation. You can identify these APIs by the presence of /identity/public/v2/extprofile/ in the endpoint URL. The APIs do require authentication, you must pass a valid access_token (Authorization header). Ensure the access token is valid before making the API call.

Example: Authentication required

curl --location 'https://{ApiOrigin|CDN}/identity/public/v2/extprofile/readlater' \
--header 'Authorization: Bearer {access_token}'

For more information about the available APIs, see Audience Insights APIs

Arc XP Audience Insights Bookmarks SDKs and APIs

As mentioned earlier, our SDK methods serve as wrappers, making it easier for developers to interact with our APIs. The following table lists the Sales SDK methods and the corresponding APIs they wrap.

SDK Method	API
addBookmark(ansId)	POST /identity/public/v2/extprofile/readlater
listBookmarks()	GET /identity/public/v2/extprofile/readlater
deleteBookmark(ansId)	DELETE /identity/public/v2/extprofile/readlater/{ansId}