SDK session improvements

Mike Stead

Mike Stead

Engineering team

As we've been building and dogfooding our sdks over recent months we've reflected on how to refine the developer experience.

Part of this journey is a healthy obsession with clean and concise APIs with minimal cognitive surface area.

While we don't intent to introduce breaking changes often, being in beta gives us some headroom to improve where we see an opportunity to.

With these points in mind we're introducing a change to our session API across our client SDKs.

What's changed

Previously when starting an mtribes session you'd call

  • session.identify(userId) for a logged in user
  • session.anonymize() for an anonymous user

We're replacing the above with

  • session.start(options)

When a userId is included in the options then we determine the user to be known and follow the old identify flow.

When no userId is provided then the user is anonymous and we follow the old anonymize flow.

You can find full details in our developer documentation.

Upgrade steps

JavaScript

Version v1.0.0-beta.7 of our JavaScript library introduces this change and marks session.identify and session.anonymize as deprecated.

Follow these steps to upgrade.

  1. Upgrade your mtribes CLI

    • osx: brew upgrade mtribes
    • win: scoop update mtribes
  2. Regenerate the integration code: mtribes update

  3. Replace calls to session.anonymize and session.identify with session.start following these examples as a guide.

session.anonymize();
// becomes
session.start();
session.anonymize(fields);
// becomes
session.start({ fields });
session.identify(userId);
// becomes
session.start({ userId });
session.identify(userId, fields);
// becomes
session.start({ userId, fields });

Android

Version v1.0.0-alpha.29 of our Android library introduces this change and marks session.identify and session.anonymize as deprecated.

Follow these steps to upgrade.

  1. Upgrade your mtribes CLI

    • osx: brew upgrade mtribes
    • win: scoop update mtribes
  2. Regenerate the integration code: mtribes update

  3. Replace calls to session.anonymize and session.identify with session.start following these examples as a guide.

kotlin

Mtribes.session.anonymize()
// becomes
Mtribes.session.start()
Mtribes.session.anonymize(fields)
// becomes
Mtribes.session.start(StartOptions(fields = fields))
Mtribes.session.identify(userId)
// becomes
Mtribes.session.start(StartOptions(userId))
Mtribes.session.identify(userId, fields)
// becomes
Mtribes.session.start(StartOptions(userId, fields))

java

Mtribes.session.anonymize()
// becomes
Mtribes.session.start()
Mtribes.session.anonymize(fields)
// becomes
Mtribes.session.start(new StartOptions(null, fields))
Mtribes.session.identify(userId)
// becomes
Mtribes.session.start(new StartOptions(userId))
Mtribes.session.identify(userId, fields)
// becomes
Mtribes.session.start(new StartOptions(userId, fields))

iOS

Version 0.2.0 of our iOS library introduces this change and marks session.identify and session.anonymize as deprecated. Follow these steps to upgrade.

  1. Upgrade the library by following these steps.
  2. Replace calls to session.anonymize and session.identify with session.start following these examples as a guide.
Mtribes.session.anonymize()
// becomes
Mtribes.session.start()
Mtribes.session.anonymize(fields: fields)
// becomes
let options = StartOptions(fields:fields)
Mtribes.session.start(options: options)
Mtribes.session.identify(userId:userId)
// becomes
let options = StartOptions(userId: userId)
Mtribes.session.start(options: options)
Mtribes.session.identify(userId: userId, fields: fields)
// becomes
let options = StartOptions(userId: userId, fields: fields)
Mtribes.session.start(options: options)

End-of-life

The deprecated functions identify and anonymize will continue to work across each SDK until our first major release v1.0.0, at which point they'll be removed.

We recommend upgrading at your next convenient opportunity.

JavaScript SDK Beta 3

Mike Stead

Mike Stead

Engineering team

We've made a couple of breaking changes in a recent release (v1.0.0-beta.3). This guide will walk you through what they are and how to upgrade.

As the JavaScript SDK is in a pre-release state, we've made these breaking changes directly. Once we pass pre-release, all versioning will follow Semver major.minor.patch to reduce this type of impact.

What's changed

Session identify and anonymize

Our SDK will now send extra properties to our platform when session.identify or session.anonymize is called.

If these properties are not sent, the calls will be rejected by our platform. This will go into effect as of Thursday 26th March at 6pm PDT.

Please let us know as soon as possible if this may cause issues.

Client configuration

Previously, the SDK client was configured using the configure function.

client.configure({
sessionLock: false,
waitTimeMsec: 1200
});

This function has been removed and you can now set client properties directly.

client.sessionLock = false;
client.waitTimeMsec = 1200;

Code generation folders

When running the CLI commands mtribes setup or mtribes update, Collection, Section and Experience types were generated into a single templates folder under the root codegen path e.g.

mtspace/spacename/templates

This folder has been removed, and template types are now generated into their associated folders.

mtspace/spacename/
- collection/
- section/
- experience/

Upgrade steps

  1. Upgrade your mtribes CLI

    • osx: brew upgrade mtribes
    • win: scoop update mtribes
  2. Regenerate the integration code: mtribes update

  3. Remove any calls to client.configure and replace them with the direct setting of client properties.

  4. Replace any imports in your code targeting the generated templates folder with the relevant categorized folder, collection, section, or experience.