Collection and Consent - Gradial Docs

ACI’s browser collector captures first-party events used by behavior-based audiences, experiments, and reporting. It is served from your site at /_aci/aci.js and sends events to the same-origin /collect endpoint.

Access: Must be enabled for your organization. Contact your Gradial team to get access.

Collection requires a personalization-enabled Gradial edge binding. A standalone framework server can render the script tag, but it does not provide the hosted collector endpoint or visitor identity.

Enable collection

Add or update the personalization block in .content/config/site.json:

{
  "personalization": {
    "collect": true,
    "consentPreset": "c15t",
    "consentCategories": "measurement,marketing"
  }
}

ACI’s Astro and Next.js integrations emit the collector tag automatically:

<script
  defer
  src="/_aci/aci.js"
  data-aci-consent="c15t"
  data-aci-consent-categories="measurement,marketing">
</script>

Do not add a second copy to an ACI-rendered site. If you maintain a custom renderer, emit the tag once in the document head and keep the stable /_aci/aci.js path. ACI supports these consent presets:

Preset	Use it when
`c15t`	Your site already exposes consent through c15t
`onetrust`	OneTrust is the consent authority
`cookiebot`	Cookiebot is the consent authority
`trustarc`	TrustArc is the consent authority
`manual`	Your application will send consent decisions through the ACI browser API

consentCategories maps the categories used by your consent manager to ACI’s personalization purpose. A preset connects to a consent manager already running on the page; it does not install a banner or define your policy. If a site does not use another consent manager, select manual and mount the supplied banner from your layout. In Astro, place this script near the end of the document body:

<script>
  import { mountConsentBanner } from '@gradial/aci/consent-banner';

  mountConsentBanner(document, {
    heading: 'Privacy choices',
    message: 'Choose whether to allow personalized content and measurement.',
    acceptLabel: 'Allow',
    rejectLabel: 'Decline',
    privacyPolicyHref: '/privacy/',
    privacyPolicyLabel: 'Privacy policy',
  });
</script>

The component exposes ACI CSS classes so you can style the banner to match your site. Review its copy and behavior with your privacy team before deployment. With consentPreset: "manual", grant the personalization purpose after a visitor opts in:

window.aci('consent', {
  p: ['personalization'],
  src: 'privacy-center'
});

Withdraw consent with an empty purpose list:

window.aci('consent', {
  p: [],
  src: 'privacy-center'
});

If your privacy UI can run before the deferred collector loads, define a small queue first:

<script>
  window.aci = window.aci || function () {
    (window.aci.q = window.aci.q || []).push(arguments);
  };
</script>

Manual consent calls are only authoritative in manual mode. For a named preset, update consent through that provider.

Track a custom event

Use the browser API for application-driven events:

window.aci('track', 'request-demo', {
  placement: 'enterprise-hero',
  plan: 'enterprise'
});

ACI records the canonical name as custom.request-demo. For markup-driven interactions, use data attributes:

<button
  data-aci-event="request-demo"
  data-aci-prop-placement="enterprise-hero"
  data-aci-prop-plan="enterprise">
  Request a demo
</button>

Track the first time an element becomes visible with data-aci-on="visible":

<section
  data-aci-event="pricing-viewed"
  data-aci-on="visible"
  data-aci-prop-plan="enterprise">
  ...
</section>

data-aci-on supports click and visible; click is the default. Attribute properties are sent as strings.

Built-in events

The collector records supported browser events such as page views, link clicks, variation views, and web-vital measurements. Use custom events for business actions that your audience criteria or goals need to identify explicitly.

Keep event names stable and describe one observable action. Prefer request-demo over a UI-specific name such as blue-button-clicked.

Behavior-based audience membership requires the configured consent and a usable first-party identity. If either is unavailable, ACI returns the base audience experience. Anonymous experiments can be configured to assign and measure visitors without creating a personalization profile. Supported browser privacy signals, including Global Privacy Control and Do Not Track, suppress identity-dependent processing. ACI provides the technical controls; your organization remains responsible for selecting purposes, categories, retention, disclosure, and deletion behavior that match its policy and legal obligations.

Export or erase an audience profile

ACI provides authenticated operations for a first-party profile identified by its ACI ID. Resolve and verify that ID through the privacy-request workflow agreed during onboarding; do not substitute an email address or another application identifier. Use the read operation to export the profile and confirm it belongs to the intended visitor:

export ACI_ID="the-visitor-aci-id"

curl \
  "$ACI_API_URL/v1/audience/memberships/$ACI_ID" \
  --header "Authorization: Bearer $ACI_API_TOKEN"

Use the delete operation to erase that profile and its associated personalization data:

Profile erasure through this endpoint cannot be undone. Confirm the ACI ID, authorization, and required record of approval before sending the request.

curl --request DELETE \
  "$ACI_API_URL/v1/audience/memberships/$ACI_ID" \
  --header "Authorization: Bearer $ACI_API_TOKEN"

Export requires read permission; erasure requires write permission. Treat exported profile data as sensitive, record the request according to your organization’s process, and verify the returned erasure result before closing the request.

Verify the integration

Inspect the rendered page

Confirm there is exactly one /_aci/aci.js script and that its consent preset and categories match site configuration.

Exercise the real consent UI

Grant and withdraw through your configured consent manager or manual integration. Confirm the UI returns to the expected state on a new page load.

Trigger a known event

Use a test interaction with data-aci-event or aci('track', ...) and confirm the page remains functional even if collection is unavailable.

Verify on an edge-backed environment

After consent, use browser developer tools to confirm same-origin requests to /collect. A local framework server does not prove this step.

Test the fallback

Repeat the journey without consent and confirm identity-dependent audience content is not selected.

Troubleshooting

The collector returns 404

Confirm the site is using its personalization-enabled Gradial edge binding. The route is not supplied by an ordinary framework server.

The script is missing

Confirm personalization.collect is true and that your ACI layout uses the current Astro or Next.js integration. Custom renderers must emit the tag once.

Behavioral targeting still shows the base experience

Check consent first, then confirm the expected event reached /collect, the segment and audience are enabled, and the updated membership is present on a later request.

Next: Experiments and Reporting →

​Enable collection

​Choose a consent integration

​Use ACI’s consent banner

​Send consent manually

​Track a custom event

​Built-in events

​Consent and targeting behavior

​Export or erase an audience profile

​Verify the integration

​Troubleshooting

Enable collection

Choose a consent integration

Use ACI’s consent banner

Send consent manually

Track a custom event

Built-in events

Consent and targeting behavior

Export or erase an audience profile

Verify the integration

Troubleshooting