> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Collection and Consent

> Connect consent, enable first-party collection, and capture events for audiences and experiments.

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.

<Info>
  Access: Must be enabled for your organization. Contact your Gradial team to get access.
</Info>

<Warning>
  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.
</Warning>

## Enable collection

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

```json theme={null}
{
  "personalization": {
    "collect": true,
    "consentPreset": "c15t",
    "consentCategories": "measurement,marketing"
  }
}
```

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

```html theme={null}
<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.

## Choose a consent integration

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.

### Use ACI's consent banner

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:

```astro theme={null}
<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.

### Send consent manually

With `consentPreset: "manual"`, grant the personalization purpose after a visitor opts in:

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

Withdraw consent with an empty purpose list:

```js theme={null}
window.aci('consent', {
  p: [],
  src: 'privacy-center'
});
```

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

```html theme={null}
<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:

```js theme={null}
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:

```html theme={null}
<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"`:

```html theme={null}
<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.

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

## Consent and targeting behavior

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:

```bash theme={null}
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:

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

```bash theme={null}
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

<Steps>
  <Step title="Inspect the rendered page">
    Confirm there is exactly one `/_aci/aci.js` script and that its consent preset and categories match site configuration.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Test the fallback">
    Repeat the journey without consent and confirm identity-dependent audience content is not selected.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Manual consent calls do nothing">
    Confirm `consentPreset` is `manual`. A named consent provider remains authoritative when its preset is selected.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

*Next: [Experiments and Reporting →](/aci/personalization/experiments-and-reporting)*