Add contextual data to your events with up to 10 custom dimensions per property.
Overview
Custom dimensions allow you to attach additional data to your analytics events. Each property supports 10 custom data slots (cd1-cd10) that can hold strings, numbers, or booleans.
Setting Custom Data
setCustomData()
// String value
alkeAnalytics.setCustomData(1, "category_tech");
// Number value
alkeAnalytics.setCustomData(2, 42);
// Boolean value
alkeAnalytics.setCustomData(3, true);
// Clear a dimension
alkeAnalytics.setCustomData(1, null);
| Parameter | Type | Description |
|---|
id | numberrequired | Dimension index (1-10) |
value | string|number|boolean|nullrequired | Value to store. Use `null` to clear. |
setCustomData() / setLateCustomData()
// Set immediately
AlkeAnalytics.setCustomData(1, value: "category_tech")
AlkeAnalytics.setCustomData(2, value: 42)
// Set as late value (updated before flush)
AlkeAnalytics.setLateCustomData(3, value: "final_value")
setCustomData()
// Set custom dimensions
AlkeAnalytics.setCustomData(1, "category_tech")
AlkeAnalytics.setCustomData(2, 42)
AlkeAnalytics.setCustomData(3, true)
Late Values
Sometimes you don’t have all data available when the pageview starts. Use late values to update dimensions before the event is sent.
setLateCustomData()
For values resolved asynchronously:
// Promise-based late value
const userTypePromise = fetchUserType();
alkeAnalytics.setLateCustomData(1, userTypePromise);
// The value will be included when the pageview flushes
// Value can be updated anytime before flush
AlkeAnalytics.setLateCustomData(1, value: "initial")
// Later, update it
AlkeAnalytics.setLateCustomData(1, value: "final")
// When flush() is called, "final" will be sent
// Value can be updated anytime before flush
AlkeAnalytics.setCustomData(1, "initial")
// Later, update it
AlkeAnalytics.setCustomData(1, "final")
// When flush() is called, "final" will be sent
Consent-Wrapped Values
For GDPR compliance, wrap sensitive values so they’re only sent when consent is granted for the specified TCF purposes.
// Only sent if user consented to purpose 1 (store/access info)
alkeAnalytics.setCustomData(1,
alkeAnalytics.holdUntilConsent(email, null, [1])
);
// With fallback value
alkeAnalytics.setCustomData(2,
alkeAnalytics.holdUntilConsent(userId, "anonymous", [1, 9])
);
// Only sent if user consented to purpose 1 (store/access info)
let emailWrapper = AlkeAnalytics.holdUntilConsent(
value: email,
defaultValue: nil,
purposes: [.storeAndAccessInformation]
)
AlkeAnalytics.setCustomData(1, value: emailWrapper)
// With fallback value
let userWrapper = AlkeAnalytics.holdUntilConsent(
value: userId,
defaultValue: "anonymous",
purposes: [.storeAndAccessInformation, .understandAudiences]
)
AlkeAnalytics.setCustomData(2, value: userWrapper)
// Only sent if user consented to purpose 1 (store/access info)
val emailWrapper = AlkeAnalytics.holdUntilConsent(
value = email,
defaultValue = null,
purposes = listOf(TCFPurpose.STORE_AND_ACCESS_INFORMATION)
)
AlkeAnalytics.setCustomData(1, emailWrapper)
// With fallback value
val userWrapper = AlkeAnalytics.holdUntilConsent(
value = userId,
defaultValue = "anonymous",
purposes = listOf(
TCFPurpose.STORE_AND_ACCESS_INFORMATION,
TCFPurpose.UNDERSTAND_AUDIENCES
)
)
AlkeAnalytics.setCustomData(2, userWrapper)
See Consent Management for more details on available purposes and behavior.
