Custom Dimensions

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.

Custom data belongs to the page it describes. Calling pushNavigation() clears the slots along with the rest of the page context, so each page declares its own — see Content Dimensions.

On the web, this only concerns single-page applications: a site that loads a real document per page is unaffected. On iOS and tvOS it concerns every application, because there is no document load to act as an implicit boundary — a screen that does not call pushNavigation() inherits the slots of the one before it.

Looking for content hierarchy, article metadata or reader context? Those are named dimensions of their own — see Content Dimensions. On the web, setDimension('cd1', value) is an alias of setCustomData(1, value), so both kinds can be set through the same call.

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.

Returns true when the value was accepted, false otherwise.

Breaking change

setCustomData() and setLateCustomData() used to return false on rejection and undefined on success. They now return a plain boolean, like setDimension() — of which setDimension('cd1', value) is an alias. Code testing the result with === undefined or typeof result === 'undefined' must be updated.

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() / setLateCustomData()

// Set immediately
AlkeAnalytics.setCustomData(1, "category_tech")
AlkeAnalytics.setCustomData(2, 42)
AlkeAnalytics.setCustomData(3, true)

// Set as late value (updated before flush)
AlkeAnalytics.setLateCustomData(4, "final_value")

Both return true when the value was accepted, false otherwise — a slot outside 1-10, or a call made before any trackPageview(), since the slot rides the page being reported.

Breaking change

setCustomData() and setLateCustomData() used to return Unit. They now return a Boolean, like setDimension() — of which setDimension("cd1", value) is an alias. Existing calls keep compiling, but a rejected value is now something you can detect rather than something that fails silently.

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

Returns true when the slot id is valid, false otherwise. The promise’s own outcome is reported in the console — a value that resolves after the event was sent is simply left out of it.

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

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.

Overview

Setting Custom Data

setCustomData()

setCustomData() / setLateCustomData()

setCustomData() / setLateCustomData()

Late Values

setLateCustomData()

Consent-Wrapped Values