Event Payload Customization Options in Mobile SDKs

Complete reference for the available event payload customization options available in the Android (Kotlin) and iOS (Swift) SDKs.

7 minute read

This guide walks you through the event payload customization options available in the RudderStack Android (Kotlin) and iOS (Swift) SDKs.

Overview

The RudderStack Android (Kotlin) and iOS (Swift) SDKs provide a RudderOption instance that lets you customize the payload for any event type. You can use this instance to pass the following parameters:

Field	Description
`integrations`	Used to specify the integrations for which the event should be sent or blocked. You can also use it to specify some specific actions to be performed for a particular integration.
`externalId`	Used to set a custom user ID or specific IDs required by some integrations.
`customContext`	Used to add custom contextual information to the event payload.

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:

Parameter	Data type	Description
`All`	Boolean	Global filtering status for all destinations. If set to `false`, RudderStack blocks the event from being sent to all destinations unless you override it with destination-specific parameters. Default value: `true`
`<Destination>`	Boolean / Object	Specific destination to filter. It overrides the `All` parameter. If the type is Object, then the SDK automatically assumes this parameter to be `true`. You can then use this field to send destination-specific configuration or data in cloud and device modes.

Default behavior

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

json

{
  //.....
  "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:

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:

kotlin

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

The corresponding Java snippet is shown below:

java

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);

swift

analytics.identify(
    userId: "User123",
    options: RudderOption(
        externalIds: [
            ExternalId(type: "brazeExternalId", id: "Brz1hGXsD")
        ]
    )
)

The corresponding Objective-C snippet is shown below:

objective-c

RSSOptionBuilder *optionBuilder = [RSSOptionBuilder new];

[optionBuilder setExternalIds:@[
    [[RSSExternalId alloc] initWithType:@"brazeExternalId" id:@"Brz1hGXsD"]
]];

[analytics identify:@"User123"
          options:[optionBuilder build]];

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

json

{
  //.....
  "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:

kotlin

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

The corresponding Java snippet is shown below:

java

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);

swift

analytics.track(
    name: "Track Event",
    options: RudderOption(
        customContext: [
            "Plan": "Enterprise",
            "Product": [
                "Type": "Accessories"
            ]
        ]
    )
)

The corresponding Objective-C snippet is shown below:

objective-c

RSSOptionBuilder *optionBuilder = [RSSOptionBuilder new];

[optionBuilder setCustomContext:@{
    @"Plan": @"Enterprise",
    @"Product": @{
        @"Type": @"Accessories"
    }
}];

[analytics track:@"Track Event"
       options:[optionBuilder build]];

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

json

{
  //.....
  "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:

kotlin

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") 
            })
        }
    )
)

The corresponding Java snippet is shown below:

java

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);

swift

analytics.track(
    name: "Track Event",
    options: RudderOption(
        customContext: [
            "Plan": "Enterprise", // Present in the final event payload
            "device": [ // Absent in the final event payload
                "id": "my-device-id",
                "name": "My Android Device"
            ]
        ]
    )
)

The corresponding Objective-C snippet is shown below:

objective-c

RSSOptionBuilder *optionBuilder = [RSSOptionBuilder new];

[optionBuilder setCustomContext:@{
    @"Plan": @"Enterprise",
    @"device": @{
        @"id": @"my-device-id",
        @"name": @"My Android Device"
    }
}];

[analytics track:@"Track Event"
       options:[optionBuilder build]];

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

json

{
	//.....
	"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:

kotlin

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 corresponding Java snippet is shown below:

java

String userId = "1hKOmRA4GRlm";

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

ExternalId externalId = new ExternalId("brazeExternalId", "Brz1hGXsD");
List<ExternalId> externalIds = Arrays.asList(externalId);

Map<String, Object> integrations = new LinkedHashMap<>();
integrations.put("Firebase", false);

RudderOption option = new RudderOptionBuilder()
        .setIntegrations(integrations)
        .setExternalId(externalIds)
        .setCustomContext(context)
        .build();

analytics.identify(userId, option);

swift

analytics.identify(
    userId: "1hKOmRA4GRlm",
    options: RudderOption(
        integrations: [
            "Firebase": false // event disabled for Firebase
        ],
        customContext: [
            "Plan": "Enterprise"
        ],
        externalIds: [
            ExternalId(type: "brazeExternalId", id: "Brz1hGXsD")
        ]
    )
)

The corresponding Objective-C snippet is shown below:

objective-c

RSSOptionBuilder *optionBuilder = [RSSOptionBuilder new];

[optionBuilder setIntegrations:@{
    @"Firebase": @NO
}];

[optionBuilder setCustomContext:@{
    @"Plan": @"Enterprise"
}];

[optionBuilder setExternalIds:@[
    [[RSSExternalId alloc] initWithType:@"brazeExternalId" id:@"Brz1hGXsD"]
]];

[analytics identify:@"1hKOmRA4GRlm"
          options:[optionBuilder build]];

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

Event Payload Customization Options in Mobile SDKs

Overview

Integration options (integrations)

integrations options

Default behavior

Custom user ID (externalId)

Custom context (customContext)

Example

Questions? Let's figure it out together.

Integration options (`integrations`)

`integrations` options

Custom user ID (`externalId`)

Custom context (`customContext`)