Skip to content

add analytics configuration details to documentation #327

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

add analytics configuration details to documentation #327

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cedd4d8
add analytics configuration details to documentation
sirugh Jun 12, 2025
69410cc
Update src/content/docs/setup/configuration/commerce-configuration.mdx
bdenham Jun 12, 2025
4d3d566
Merge branch 'develop' into analytics-config
sirugh Jun 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 46 additions & 9 deletions src/content/docs/setup/configuration/commerce-configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ In this section, you'll learn how Commerce blocks in your storefront connect to
In the [Create your storefront tutorial](/get-started/), the template repo provided you a `demo-config.json` file in the root folder. This file contains the environment values for a Commerce backend including GraphQl endpoints and headers.

When implementing your own project, you must update the configuration values with:
- The header values specific to your Adobe Commerce Catalog Services environment.
- The header and analytics values specific to your Adobe Commerce and Adobe Commerce Catalog Services environment.
- The Adobe Commerce and Catalog Service GraphQL endpoint that you configured as part of the [content delivery network (CDN) setup](/setup/configuration/content-delivery-network/).

## Vocabulary
Expand Down Expand Up @@ -68,15 +68,19 @@ You can find the config file in your code repo at either /config.json or /demo-c
}
},
"analytics": {
"base-currency-code": "USD",
"environment": "Production",
"store-id": 1,
"base-currency-code": "{{YOUR_BASE_CURRENCY_CODE}}",
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually think we should maybe rethink how the data is displayed. I don't like all these placeholders, it feels repetitive. Perhaps we provide an example, then describe them in detail below.

We also have an opportunity here to make a tool that takes an API url, makes a query for these values, and returns the config object exactly as should be saved in config.json, or uploaded to public config.

Copy link
Contributor Author

@sirugh sirugh Jun 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something like this? Ignore the keys/values in the screenshot - just a quick poc.

https://da.live/app/adobe-commerce/storefront-tools/tools/config-generator/config-generator

IMG_2784

"environment": "{{PRODUCTION_OR_TESTING}}",
"environment-id": "{{YOUR_ENVIRONMENT_ID}}",
"store-code": "{{YOUR_STORE_CODE}}",
"store-id": "{{YOUR_STORE_ID}}",
"store-name": "Main Website Store",
"store-url": "{{YOUR_STORE_URL}}",
"store-view-id": 1,
"store-view-code": "{{YOUR_STOREVIEW_CODE}}",
"store-view-id": "{{YOUR_STORE_VIEW_ID}}",
"store-view-name": "Default Store View",
"website-id": 1,
"website-name": "Main Website"
"website-code": "{{YOUR_WEBSITE_CODE}}",
"website-id": "{{YOUR_WEBSITE_ID}}",
"website-name": {{YOUR_WEBSITE_NAME}}"
}
}
}
Expand All @@ -94,7 +98,7 @@ Each `key` is described below with links to more details. The `value` for each k

1. **commerce-core-endpoint:** (read/write) Core GraphQL endpoint for a variety of queries and mutations. See [Adobe Commerce GraphQL API](https://developer.adobe.com/commerce/webapi/graphql/reference/) for details.

1. **headers.all.Store:** Determines the store view to connect to, for Core requests. See [Core GraphQL Headers documentation](https://developer.adobe.com/commerce/webapi/graphql/usage/headers/) for details.
1. **headers.all.Store:** Determines the store view to connect to, sent with all GraphQL requests. See [Core GraphQL Headers documentation](https://developer.adobe.com/commerce/webapi/graphql/usage/headers/) for details.

1. **headers.cs.Magento-Environment-Id:** Connects the storefront to the cloud instance that serves it. See [Cloud Environment overview](https://experienceleague.adobe.com/en/docs/commerce-cloud-service/user-guide/project/overview#environment-overview) for details.

Expand All @@ -109,9 +113,42 @@ Each `key` is described below with links to more details. The `value` for each k
1. **headers.cs.x-api-key:** Provides access to SaaS storefront services (Catalog Service, Live Search, and Product Recommendations). See [Commerce Services Connector](https://experienceleague.adobe.com/en/docs/commerce/user-guides/integration-services/saas) for details.

</Callouts>

All of the initializer blocks now automatically use any headers for the corresponding block if they are in the config. For example `commerce.headers.cart.Foo` will add a `Foo` header to graphql requests made by the cart dropin. This can be useful if you need to append certain headers for specific requests.

Each `analytics` key, used to instantiate Storefront Instance Context, is described below with links to more details. The `value` for each key is specific to your Commerce instance and can be provided by your Commerce administrator.

For type definitions of the analytics configuration properties, see the [storefrontInstance.ts](https://github.com/adobe/commerce-events/blob/main/packages/storefront-events-sdk/src/types/schemas/storefrontInstance.ts) file in the commerce-events repository.

<Callouts>
1. **analytics.base-currency-code:** The base currency code for the store. See [Currency Setup](https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/site-store/currency/currency-setup) for details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page doesn't appear to exist. Do you mean https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/site-store/currency/currency-configuration?

Or https://experienceleague.adobe.com/en/docs/commerce-admin/config/general/currency-setup

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep - we should fix these broken links. Cursor tried it's best :P


1. **analytics.environment:** The environment type (e.g., "Production", "Testing"). See [Cloud Environment overview](https://experienceleague.adobe.com/en/docs/commerce-cloud-service/user-guide/project/overview#environment-overview) for details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about ACCS (e.g., sandbox vs production)? Not much in the wayof docs to reference, but here are a couple:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@shiftedreality maybe you know the difference here between Production and Testing value being provided to this arg.


1. **analytics.environment-id:** The unique identifier for your Commerce Cloud environment. See [Cloud Environment overview](https://experienceleague.adobe.com/en/docs/commerce-cloud-service/user-guide/project/overview#environment-overview) for details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about ACCS? Is tenant ID the same thing?

https://experienceleague.adobe.com/en/docs/commerce/cloud-service/getting-started#access-an-instance

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I think so.


1. **analytics.store-code:** The code that identifies your store. See [Step 3: Create stores](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-3-create-stores) for details.

1. **analytics.store-id:** The unique identifier for your store. See [Step 3: Create stores](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-3-create-stores) for details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the linked page, I only see info about web site, name, code, and root category. Which one does analytics.store-id map to?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know. It's in the schema. Not sure what it's meant to be :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a chance to dig into the questions around where to find the *-id values for the store, store view and web site entities. Shout out to Russell Albin for clarifying.

These IDs aren't exposed in the Admin UI the same way that other properties are, for example code and name. Apparently, the easiest way to find the ID is to click through an entity in the Admin UI and look at the URL.

Alternatively, you can find the value in the app/etc/config.php file or by running a DB query. However, those alternative methods are not available for ACCS customers.

@sirugh, I saw your internal Slack message this morning asking if we really need the IDs or if we can just rely on code. I think it would be best to get that clarification before proceeding with this PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally we don't make non-technical users even aware of any of this :D

Partially why I made the tool to automate config generation (as best it could).

The real question we need to resolve is what exact information is necessary to send in analytics, and how do we (or a merchant) get that info?


1. **analytics.store-name:** The display name of your store. See [Step 3: Create stores](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-3-create-stores) for details.

1. **analytics.store-url:** The base URL for your store. See [Store URLs](https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/site-store/store-urls) for details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about ACCS? The link goes to a page that has a PaaS only badge.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TBH I thought that maybe we should remove all the links here. We are allowing users a way to dynamically define values used in storefront instance context. That context, hopefully, has documentation about what should be set in a frontend for headless commerce.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably replace links to the Admin Guides with a link to GraphQL query (or queries if we need a different one for ACO).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right - it's crazy to make someone have to make this themselves. Best thing we could do is automate it for them.


1. **analytics.store-view-code:** The code that identifies your store view. See [Step 4: Create store views](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-4-create-store-views) for details.

1. **analytics.store-view-id:** The unique identifier for your store view. See [Step 4: Create store views](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-4-create-store-views) for details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the linked page, I only see info about store, name, code, and status. Which one does analytics.store-view-id map to?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know. It's in the schema. Not sure what it's meant to be :)


1. **analytics.store-view-name:** The display name of your store view. See [Step 4: Create store views](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-4-create-store-views) for details.

1. **analytics.website-code:** The code that identifies your website. See [Step 2: Create websites](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-2-create-websites) for details.

1. **analytics.website-id:** The unique identifier for your website. See [Step 2: Create websites](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-2-create-websites) for details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the linked page, I only see info about name, code, and sort order. Which one does analytics.website-id map to?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know. It's in the schema. Not sure what it's meant to be :)


1. **analytics.website-name:** The display name of your website. See [Step 2: Create websites](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/multi-sites/ms-admin#step-2-create-websites) for details.

</Callouts>


## Step-by-step

We'll use a mock PDP / Catalog Service block as an example of where and how to utilize the various config utilities and values.
Expand Down