Migrating from v3

Batch Web SDK v4 is a major release, which introduces breaking changes from 3.x. This guide describes how to update the script in a website already using a previous version.

Upgrading the SDK version

To upgrade from v3 to v4, you need to change the SDK version in two places:

• On your page script or tag manager, replace https://via.batch.com/v3/bootstrap.min.js with https://via.batch.com/v4/bootstrap.min.js.

• Download the new SDK files and update your service worker implementation

  • If you're using batchsdk-worker-loader.js, simply replace this file with the new one.

  • If you added Batch in your custom service worker implementation, set BATCHSDK_MAJOR_VERSION's value to 4.

Service worker configuration

This version introduced a new way of configuring your service worker implementation and especially if you need to specify a registration for a sub-scope that does not control the current page.

If you were using serviceWorkerPathOverride, useExistingServiceWorker or serviceWorkerTimeout to integrate Batch with your own service worker (or uploading to a folder of your site), you will have to modify the Batch's SDK setup as following since this keys does not exist anymore.

 batchSDK('setup', {
   ...,
   
   // Optional service worker related configuration.
   serviceWorker: {
     
     // Optional - default: 10 seconds. 
     // Maximum waiting time for your Service Worker to be ready. 
     // Replaces `serviceWorkerTimeout` but works the same.
     waitTimeout: 5,

     // Optional - default: true. 
     // Whether Batch should automatically register its service worker.
     // Replaces `useExistingServiceWorker` and works in the opposite way (default true, false to disable).
     automaticallyRegister: false,

     // Optional. A promise that resoves a service worker registration.
     // Allows you to have Batch use a specific Service Worker registration.  
     // This can be a Service Worker registration for a sub-scope that does not control the current page.
     // Requires `automaticallyRegister` to be false.
     registration: navigator.serviceWorker.register("your_custom_path")
   }
  });

When using registration, Batch can't check that your Service Worker will properly work, your integration might break if your SW is not valid for push notifications.

For more information, please see the following sections :

• Uploading the Service Worker to a folder of your website

• Integrating Batch with an existing Service Worker

• Registering a Service Worker in a sub-scope

Profile data collection

Data collection

This version follows Batch's pivot to being an omnichannel platform. It allows you to collect data for your Projects and Profiles. If you are not familiar with these two concepts, please see this guide beforehand.

First of all, most of the user-related write APIs have been removed. Reading methods are still usable since we do not provide yet a way to get synced data for a Profile, but keep in mind that the data returned is only about your installation and not your Profile.

To interacts with our user-centered model, you should now use the profile() method. Let's see a migration example.

If you were previously doing something like that:

batchSDK(api => {
  api.setCustomUserID("custom_user_id");
  api.setUserLanguage("en")
  api.setUserRegion("EN")
  api.editUserData(editor => {
    editor.removeAttribute("age")
    editor.setAttribute("is_premium", true);
    editor.addTag("favorites", "fashion")
    editor.addTag("interests", "shoes");
    editor.removeTag("interests", "cars")
  });
  api.setCustomUserID(null)
});

You should now do:

JavaScript (ES8)

batchSDK(async api => {
    const profile = await api.profile();
    await profile.identify({customId: "custom_user_id"});
    await profile.edit(editor => {
      editor.setLanguage("en")
        .setRegion("EN")
        .removeAttribute("age")
        .setAttribute("is_premium", true)
        .setAttribute("favorites", ["fashion"])
        .addToArray("interests", ["shoes"])
        .removeFromArray("interests", ["cars"])
    })
    await profile.identify(null);
});

JavaScript

batchSDK(api => {
    api.profile().then(profile => {
      profile.identify({customId: "custom_user_id"}).then(profile => {
        profile.edit(editor => {
          editor.setLanguage("en")
            .setRegion("EN")
            .removeAttribute("age")
            .setAttribute("is_premium", true)
            .setAttribute("favorites", ["fashion"])
            .addToArray("interests", ["shoes"])
            .removeFromArray("interests", ["cars"])
        }).then(profile => {
          profile.identify(null)
        })
      })
    })
});

To see in details what's precisely changed since V3 please consult our changelog or visit the APIs Reference.

For more information, please see the following sections :

• Custom user id

• Custom region/language

• Custom user attributes

• Email subscription

Data migration

To make it easier to collect data to a Profile, Batch has added two automatic ways to migrate old installation's data on a Profile. So the first time a user will visit your website running on v4 :

• He will be automatically identified (logged-in) if he had a Batch custom_user_id set on the local storage.

• Its natives (language/region) and customs data will be automatically migrate to a Profile if your app is attached to a Project.

You may want to disable these migrations, to do so please update your Batch's SDK setup as following:

batchSDK('setup', {
  ...,
  // Optional - migrations related configuration.
  migrations: {
  
    // Optional - Specific SDK v4 migrations
    v4: {
  
      // Whether Batch should automatically identify logged-in user when running the SDK for the first time.
      // This mean user with a custom_user_id will be automatically attached a to a Profile  and can be targeted within a Project scope.
      // Optional - default: true
      customID: false,
  
      // Whether Batch should automatically attach current installation's data (language/region/customDataAttributes...)
      // to the User's Profile when running the SDK for the first time.
      // Optional - default: true
      customData: false,
    }
  }
});

Event data

Batch Web SDK v4 introduced two new types of attribute that can be attached to an event : Array and Object.

We also took the liberty of updating the tracking event method.

What's change:

• Optional tag attribute is no longer available and has been replaced by $tags as reserved key under the attributes object.

• Optional label attribute is no longer available and has been replaced by $label as reserved key under the attributes object.

Limits are unchanged and still 200 chars max for $label and 10 items max for $tags .

So if you were previously doing something like:

batchSDK(api => {
  api.trackEvent("add_to_cart", {
    label: "accessories",
    tags: ["winter-sale", "woman"],
    attributes: {
      sub_category: "bags", 
      product_page_url: new URL("https://batch.com/product-page"),
      end_of_sale_date: new Date("2022-02-08T15:00:00Z"),
    },
  });
})

You should now do:

batchSDK(api => {
  api.trackEvent("add_to_cart", {
    attributes: {
      sub_category: "bags", 
      product_page_url: new URL("https://batch.com/product-page"),
      end_of_sale_date: new Date("2022-02-08T15:00:00Z"),
      $label: "accessories",
      $tags: ["winter-sale", "woman"],
    },
  });
})

For more information, please visit our custom event guide.