Skip to main content

SDK session improvements

· 3 min read
Mike Stead

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();// becomessession.start();
session.anonymize(fields);// becomessession.start({ fields });
session.identify(userId);// becomessession.start({ userId });
session.identify(userId, fields);// becomessession.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()// becomesMtribes.session.start()
Mtribes.session.anonymize(fields)// becomesMtribes.session.start(StartOptions(fields = fields))
Mtribes.session.identify(userId)// becomesMtribes.session.start(StartOptions(userId))
Mtribes.session.identify(userId, fields)// becomesMtribes.session.start(StartOptions(userId, fields))

java#

Mtribes.session.anonymize()// becomesMtribes.session.start()
Mtribes.session.anonymize(fields)// becomesMtribes.session.start(new StartOptions(null, fields))
Mtribes.session.identify(userId)// becomesMtribes.session.start(new StartOptions(userId))
Mtribes.session.identify(userId, fields)// becomesMtribes.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()// becomesMtribes.session.start()
Mtribes.session.anonymize(fields: fields)// becomeslet options = StartOptions(fields:fields)Mtribes.session.start(options: options)
Mtribes.session.identify(userId:userId)// becomeslet options = StartOptions(userId: userId)Mtribes.session.start(options: options)
Mtribes.session.identify(userId: userId, fields: fields)// becomeslet 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.