30

Upgrade from 3.4x to 4x

This page provides steps to help you upgrade from react native 3.4 or later so you understand the development effort required to update your app and take advantage of the latest features.

What changed?

This update provides native support for Data PipelinesCustomer.io’s customer data platform, helping you capture data from your sources, transform it, and send it to destinations where you can act on it. Data Pipelines is also the preferred integration path for your Customer.io workspace, as it supports all of our Journeys features and other destinations that rely on your data. as a part of the Customer.io SDK. While this represents a significant change “under the hood,” we’ve tried to make it as seamless as possible for you; much of your implementation remains the same.

This move also adds two additional features:

• Support for anonymous tracking: you can send events and other activity for anonymous users, and we’ll reconcile that activity with a person when you identify them.
• Built-in lifecycle events: the SDK now automatically captures events like “Application Installed” and “Application Updated” for you.
• New device-level data: the SDK captures the device name and other device-level context for you.

If you’re new to Data Pipelines, don’t worry! It’s free and it’s very similar to our other APIs. We’ll walk you through the process to set up your React Native app as a data sourceA source is a website or server that you want to capture data from—it’s a source of data! and everything.

When you’re done, you’ll be able to use your app’s data in both Customer.io and other downstream destinations—like your analytics platform, data warehouse, or CRM. All that and you’ll be prepared to accept new features and improvements that we roll out in the future!

Upgrade process

You’ll update initialization calls for the SDK itself and the push and/or in-app messaging modules.

As a part of this process, your credentials change. You’ll need to set up a new data sourceA source is a website or server that you want to capture data from—it’s a source of data! in Customer.io and get a new CDP API Key. But you’ll also need to keep your previous siteId as a migrationSiteId when you initialize the SDK. The migrationSiteId is a key helps the SDK send remaining traffic when people update your app.

When you’re done, you’ll also need to change a few base properties to fit the new APIs. In general, identifier becomes userId, body becomes traits, and data becomes properties.

1. Get your new CDP API Key

The new version of the SDK requires you to set up a new data sourceA source is a website or server that you want to capture data from—it’s a source of data! in Customer.io. As a part of this process, you’ll get your CDP API Key.

1. Go to the Data Pipelines tab. On the Connections page under Sources, click Add Source.
2. Select the Mobile: React Native source and then click Next: Connect React Native.

   

   
3. Enter a Name for the source, like “My React Native App”.
4. We’ll present you with a code sample containing a cdpApiKey that you’ll use to initialize the SDK. Copy this key and keep it handy.
5. Click Complete Setup to finish setting up your source.

   

   

Now the Connections page shows that your React Native source is connected to your Journeys workspace. Hover over a source or destination to see its active connections. You can also connect your React Native source to additional destinations if you want to send your mobile data to additional services—like your analytics provider, data warehouse, or CRM.

2. Update your initialization

You’ll initialize the new version of the SDK and its packages with CioConfig objects instead of CustomerioConfig. While we’ve listed all the new configuration options, you’ll want to pay close attention to the following changes:

• CustomerIOEnv is no longer necessary.
• Region becomes CioRegion.
• siteId becomes migrationSiteId.
• You’ll initialize the SDK with initialize(config) instead of initialize(env, config).

import {
  CioLogLevel, CioRegion, CustomerIO, CioConfig
} from 'customerio-reactnative';
  
const config: CioConfig = {
  cdpApiKey: 'cdp_api_key', // Mandatory
  migrationSiteId: 'site_id', // For migration
  region: CioRegion.US,
  logLevel: CioLogLevel.Debug,
  trackApplicationLifecycleEvents: true,
  inApp: {
    siteId: 'site_id', // this removes the use of enableInApp and simplifies in-app configuration
  },
  push: {
    android: {
      pushClickBehavior: PushClickBehaviorAndroid.ResetTaskStack
    }
  }
};
CustomerIO.initialize(config)

3. Update your push notification handler

In your PushNotificationsHandler.swift (or the associated file where you add a push notification handler), you can remove the CioTracking module and the initialize method.

If you write native code in Objective-C, you’ll also need to update your MessaginPushAPN or MessagingPushFCM initialization. We’ve highlighted the lines you’ll need to remove or modify in the code sample below.

import Foundation
import CioMessagingPushAPN
// remove this line
import CioTracking  

@objc
public class MyAppPushNotificationsHandler : NSObject {

  public override init() {}

  @objc(setupCustomerIOClickHandling)
  public func setupCustomerIOClickHandling() {
    // remove this line
    CustomerIO.initialize(siteId: "siteId", apiKey: "apiKey", region: .US) { config in }

    // update this line to 
    // MessagingPushAPN.initialize(withConfig: MessagingPushConfigBuilder().build())
    MessagingPushAPN.initialize(configOptions: nil)
  }

  @objc(application:deviceToken:)
  public func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    MessagingPush.shared.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
  }

  @objc(application:error:)
  public func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    MessagingPush.shared.application(application, didFailToRegisterForRemoteNotificationsWithError: error)
  }
}

import Foundation
import CioMessagingPushFCM
import FirebaseMessaging
// remove this line
import CioTracking

@objc
public class MyAppPushNotificationsHandler : NSObject {

  public override init() {}

  @objc(setupCustomerIOClickHandling)
  public func setupCustomerIOClickHandling() {
    // remove this line
    CustomerIO.initialize(siteId: Env.siteId, apiKey: Env.apiKey, region: Region.US) { config in }
    
    // update this line to
    // MessagingPushFCM.initialize(withConfig: MessagingPushConfigBuilder().build())
    MessagingPushFCM.initialize(configOptions: nil)    
  }

  // Register device on receiving a device token (FCM)
  @objc(didReceiveRegistrationToken:fcmToken:)
  public func didReceiveRegistrationToken(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    MessagingPush.shared.messaging(messaging, didReceiveRegistrationToken: fcmToken)
  }
}

4. Update your identify call

Our APIs changed slightly in this release. We’ve done our best to make the new APIs as similar as possible to the old ones. The names of a few properties that you’ll pass in your calls have changed, but their functionality has not.

• identify: identifier becomes userId and body becomes traits
• track and screen calls are structured the same as previous versions, but the data object is now called properties.

We’ve highlighted changes in the sample below.

//identify: identifier becomes userId, body becomes traits
CustomerIO.identify({
  userId: "user_id", 
  traits: {
    first_name: "user_name",
    email: "email_identifier",
  },
});

//track: no significant change to method 
//in Customer.io data object renamed properties
CustomerIO.track("track_event_name", { 
  propertyName: propertyValue 
});

//screen: no significant change to method.
//name becomes title, data object renamed properties
CustomerIO.screen("screen_event_name", { 
  propertyName: propertyValue 
});

Configuration Changes

As a part of this release, we’ve changed a few configuration options when you initialize the SDK. You’ll use CioConfig to set your configuration options. The following table shows the changes to the configuration options.