customAttributes

Learn how to use custom attribute to send additional information about your web events.

Custom attributes are optional properties that can be set on a Journey event to pass additional information about the event.

Use customAttribute in the following cases:

• To display the information to an agent handling the interaction with customer or viewing customer's web session.
• To use the information to match segments or to trigger action maps.

Format

To track Journey web events with custom attributes, include the custom attributes in the Journey tracking command arguments.

Ensure that the custom attribute you add to the event following the format below:

• Meaningful name - Since the custom attribute name is displayed as a tooltip for agents watching the customer journey and for administrators who add the event to a segment or an action, ensure you have a meaningful name with a quick recall value. For example: productPrice, totalValue, catalogNumber.
• Associated value - Genesys Cloud supports three primitive JavaScript types and one specific object type:
  • The primitive values supported are number, string, and boolean.
  • The customAttribute object type can have a dataType (of type integer, number, string, and boolean) and a value based on the specified dataType. For example, if the dataType is 'integer', the value could be 123.

In the following example, we have added the custom attribute to the event product_added to the record command.

ac('record', 'product_added', { 
          price: 15.99,
          productCode: 'CDE-123', 
          productName: 'Product', 
          hasBatteries: false, 
          quantity: {
                  dataType: 'integer',
                  value: '12'
                       } 
});

Validation

Ensure that the custom attributes follow the rules below. Invalid custom attributes are dropped and therefore cannot be used by admins nor can be seen by agents.

• The attribute value cannot be null or undefined.
• The attribute value cannot be an empty string.
• The customAttribute must contain both dataType and value. Both the keys must contain a string value, and the value attribute must match the string you specified for the 'dataType'. For example, if the dataType is 'Boolean', the value can be 'True'. The value must not be set to 'Yes'.
• The attribute 'dataType' is associated with the specified event attribute when first processed. To use a different dataType, create an event with a different name or an attribute with a different name.

Event and eventType validation

The following rules apply to event type that contains custom attributes:

• A maximum of 20 attributes is allowed for an event. When the number of attributes is greater than 20, the event is not recorded.
• A maximum of 50 unique attributes is allowed for an event type. When the number of unique attributes is greater than 50, the event types will not store the attribute definitions. However, the event will be processed as normal.
• For changing the event type and all associated custom attribute names and data types, use the Journey Event Types Public API. See Event types.