Event Payload Customization Options

This guide walks you through the event payload customization options available in the Kotlin SDK.

Overview

The Kotlin SDK provides a RudderOption instance that lets you customize the payload for any event type. You can use this instance to pass the following parameters:

The SDK does not persist the information set using the integrations, externalId, and customContext fields across different events.

Therefore, you must pass these parameters every time you want to add the information to an event.

Integration options (integrations)

You can use the integrations field of the RudderOption instance to define the integration options for an event. These options include:

• Allowing or blocking an event from being sent to a particular destination (in cloud, device, or hybrid mode)
• Passing specific configuration or data to a particular destination

integrations options

The integrations field accepts the following parameters:

Default behavior

By default, the integrations object is configured to send the event to all destinations which are present and initialized.

{
  //.....
  "integrations": {
    "All": true
  },
  //.....
}

You can override this behavior by tweaking the integrations object to allow or block specific destinations, or send any destination-specific information, as per your use case.

See the following guides for more information:

• How to allow or block an event for a specific destination
• How to send destination-specific configuration or data

Custom user ID (externalId)

The externalId field of the RudderOption instance is used to set a custom user ID or specific IDs required by some integrations. RudderStack adds this value under the context.externalId field of the event payload.

The following snippet demonstrates how to add a custom externalId to your identify event before sending it to the Braze destination:

analytics.identify(
    userId = "1hKOmRA4GRlm",
    options = RudderOption(
        externalIds = listOf(
            ExternalId(type = "brazeExternalId", id = "Brz1hGXsD")
        )
    )
)

List<ExternalId> externalIds = new ArrayList<>();
externalIds.add(new ExternalId("brazeExternalId", "Brz1hGXsD"));

Map<String, Object> traits = new HashMap<>(); // Define empty traits map

RudderOption option = new RudderOptionBuilder()
        .setExternalId(externalIds)
        .build();

analytics.identify("1hKOmRA4GRlm", traits, option);

After making the above call, the custom ID will be added to the context.externalId field of the event payload, as shown:

{
  //.....
  "context": {
    //......
    "externalId": [{
      "id": "Brz1hGXsD",
      "type": "brazeExternalId"
    }],
    //......
  }
  //.....
}

Custom context (customContext)

The customContext field of the RudderOption instance is used to add custom contextual information to the event payload. This field is a JSON object that can contain any key-value pairs.

The following snippet demonstrates how to add custom context to your track event:

analytics.track(
    name = "Track Event",
    properties = Properties(emptyMap()),
    options = RudderOption(
        customContext = buildJsonObject {
            put("Plan", "Enterprise")
            put("Product", buildJsonObject {
                put("Type", "Accessories")
            })
        }
    )
)

String name = "Track Event";

Map<String, Object> context = new HashMap<>();
context.put("Plan", "Enterprise");
context.put("Product", Map.of("Type", "Accessories"));

RudderOption option = new RudderOptionBuilder()
                .setCustomContext(context)
                .build();

analytics.track(name, option);

After making the above call, the custom context will be added to the context field of the event payload, as shown:

{
  //.....
  "context": {
    //.....
    "Plan": "Enterprise",
    "Product": {
      "Type": "Accessories"
    },
    //....
  }
  //.....
}

Note that you cannot use the customContext field to override the default contextual fields set by the SDK. For example, if you set the device field in the customContext object, the SDK ignores it and uses the default device information instead. An example is shown below:

analytics.track(
    name = "Track Event",
    properties = Properties(emptyMap()),
    options = RudderOption(
        customContext = buildJsonObject {
            put("Plan", "Enterprise") // This will reflect in the final event payload
            put("device", buildJsonObject {  // This won't reflect in the final event payload
                put("id", "my-device-id")
                put("name", "My Android Device") 
            })
        }
    )
)

String name = "Track Event";

Map<String, Object> context = new HashMap<>();
context.put("Plan", "Enterprise");
context.put("device", Map.of("id", "my-device-id", "name", "My Android Device"));

RudderOption option = new RudderOptionBuilder()
                .setCustomContext(context)
                .build();

analytics.track(name, option);

After making the above call, the context field of the event payload will contain the following:

{
	//.....
	"context": {
      //.....
      "Plan": "Enterprise",
      "device": { // The default device info captured by the SDK
          "id": "d190f76ea636bc44",
          "manufacturer": "Google",
          "model": "sdk_gphone64_arm64",
          "name": "emu64a",
          "type": "Android"
      },
      //.....
  }
  //.....
}

Overriding default contextual fields

RudderStack does not recommend overriding the default contextual fields set by the SDK as it can lead to unexpected issues.

However, if you wish to do so, you can use a custom plugin to override the default contextual fields.

Example

The following snippet demonstrates how to use the RudderOption instance to customize the event payload:

analytics.identify(
    userId = "1hKOmRA4GRlm",
    options = RudderOption(
        integrations = buildJsonObject {
            put("Firebase", false) // Event disabled for Firebase
        },
        externalIds = listOf(
            ExternalId(type = "brazeExternalId", id = "Brz1hGXsD")
        ),
        customContext = buildJsonObject {
            put("Plan", "Enterprise")
        }
    )
)

The above snippet:

• Disables the identify event for the Firebase integration through the integrations parameter
• Sets a custom user ID for the Braze integration through the externalId parameter
• Adds custom contextual information (Plan: Enterprise) to the event payload through the customContext parameter

Questions? Contact us by email or on Slack