Using Transformations in Device Mode

You can use RudderStack’s Transformations feature with the device mode-supported destinations like Firebase, Hotjar, etc.

• Only the JavaScript, Android, and iOS SDKs support device mode transformations.
• RudderStack supports writing device mode transformations only in JavaScript.
• The transformations you use in device mode must adhere to the RudderStack message schema. Otherwise, the event will be dropped.

Connect device mode transformation

1. Write the transformation to connect to your device mode destination.
2. Set up your device mode destination in RudderStack.

Note that:

• To set up a device mode destination, choose the connection mode as Device mode while configuring your destination.

• In some cases, setting up a device mode destination involves enabling the Use device mode to send events toggle while configuring the destination.

• You can change the connection mode after the destination is set up. Go to the destination’s Configuration tab and click Edit configuration.

• Some destinations support only device mode. See the destination-specific documentation for the supported connection modes.

3. Go to Collect > Transformations and select the transformation to connect to this destination.

Device mode transformations can be enabled only from the Transformations tab.

4. Click the Connections tab . If you don’t have any destinations connected to it, click Connect Destination. If the transformation already has connected destinations, click Manage destinations.

Depending on whether the destination you set up (in Step 1) is already connected to some transformation, there are two ways to add a device mode transformation to it:

• If your destination is not connected to any transformation click Connect. You will see a fly window with these options:

• If your destination is already connected to some other transformation, click the Edit connections button to switch your transformation. See Switch transformation for more information. Once you switch the transformation, you will see the above options to enable the device mode transformation.

6. Configure the following settings under Device Mode:

Under Cloud Mode, the Connect to transformation toggle is enabled by default. Do not disable this toggle as it will not allow you to configure any device mode transformation settings.

• Enable the Connect to transformation toggle.
• Enable the Propagate errors toggle depending on your requirement.

Note that:

• If Propagate errors is enabled, RudderStack sends the events to the destination without transforming the events, for any transformation errors. This is helpful in preventing data loss in case of transformation code or runtime errors.
• If your transformation involves hashing PII, enabling this setting will send the untransformed event data in case of any transformation errors.

7. Click Save to confirm the settings and for the changes to take effect.

To confirm that the device mode transformation is connected, go to the Connections tab of your transformation and check the Connection Mode column:

SDK setup

After adding a transformation and connecting it to a destination supporting device mode, you can connect your SDK source to it.

Follow the below steps for setting up the required SDK:

<script type="text/javascript">
!function(){var e=window.rudderanalytics=window.rudderanalytics||[];e.methods=["load","page","track","identify","alias","group","ready","reset","getAnonymousId","setAnonymousId","getUserId","getUserTraits","getGroupId","getGroupTraits","startSession","endSession","getSessionId"],e.factory=function(t){return function(){e.push([t].concat(Array.prototype.slice.call(arguments)))}};for(var t=0;t<e.methods.length;t++){var r=e.methods[t];e[r]=e.factory(r)}e.loadJS=function(e,t){var r=document.createElement("script");r.type="text/javascript",r.async=!0,r.src="https://cdn.rudderlabs.com/v1.1/rudder-analytics.min.js";var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(r,a)},e.loadJS(),
e.load(WRITE_KEY,DATA_PLANE_URL),
e.page()}();
</script>

implementation 'com.rudderstack.android.sdk:core:1.16.0'

pod 'Rudder', '1.17.0'

Tokenization

RudderStack provides the tokenization feature in device mode transformations to add an extra layer of security. The token is available as a metadata in the transformation and you can validate it before attaching with the RudderStack SDK.

A sample code to access the token in the transformation:

export function transformEvent(event, metadata) {
  const dmtToken = metadata(event)["Custom-Authorization"];
  //verify the token
  ...
  return event;
}

You can use the following methods to attach the token (in the string format) to the SDK:

rudderanalytics.setAuthToken("my-token");

RudderClient.putAuthToken("my-token")

[RSClient putAuthToken:@"my-token"];

You can call these methods multiple times.

RudderStack clears the token when the user logs out, that is, when the reset() API is called.

Hybrid mode transformations

While using transformations with hybrid mode destinations like GA4, Braze, Leanplum, or Rockerbox, you can choose to transform:

• Both the cloud and device mode events: By default, the transformation is applied to both the cloud and device mode events.
• Only device mode events: Access the mode field in your transformation’s event metadata and check if its value is deviceMode. Then, specify the transformation logic to be applied to the device mode events:

export function transformEvent(event, metadata) {

  const mode = metadata(event)["mode"];
  if(mode === "deviceMode") {
      //some transformation
      return event;
    }

    return event;
}

• Only cloud mode events: Return the device mode events as it is using the mode field and specify the transformation logic for the rest of the events (cloud mode events), as shown:

export function transformEvent(event, metadata) {

  const mode = metadata(event)["mode"];
  if(mode === "deviceMode") {
      return event;
    }

    ... //some transformation
    return event;
}

Client Transformation service architecture

RudderStack provides the Client Transformation service to facilitate transformations for device mode destinations. It ensures that the event ingestion to RudderStack backend isn’t affected, assuring minimum response time from the RudderStack backend.

When you add a transformation and connect it to a destination supporting the device mode:

1. RudderStack SDK sends the event to the Client Transformation service. It multiplexes the event for different destinations and connects with the transformations attached to these device mode destinations.
2. Client Transformation service sends the event to the RudderStack Transformation service to transform the event according to the functions defined in the attached transformations.
3. After the transformation is applied, the transformed event is returned to the Client Transformation service.
4. Client Transformation service responds to the SDK with the transformed events for all the destinations.
5. Finally, the SDK parses the transformed events and forwards them to the specified device-mode destinations.

If the request to the Client Transformation service fails, the RudderStack SDK makes three retry attempts. If it fails, the SDK forwards the untransformed events to the destination or drops them - based on the Propagate errors toggle while configuring the device mode transformation (see Step 6).

Limitations

The following limitations are applicable when invoking a transformation in device mode:

• The native destination SDKs might persist some captured data - mainly identifiers and traits. So, in device/hybrid mode, you cannot transform these fields using device mode transformations.

• Network unavailability can lead to higher latency than expected while sending the events to the destinations. RudderStack doesn’t lose data due to the network loss and stores the events in the client device until they are successfully delivered to the destination.

• The iOS SDK does not support the background processing of an event when the app is closed. However, it sends the pending events the next time the app is opened.

• The transformation must follow the below memory and time limits:

  Parameter	Limit
  Memory limit	128 MB
  Execution time limit	4 seconds

Questions? Contact us by email or on Slack