Skip to main content

· 2 min read
Chris Palmer

Recently we released event-based Tribes, allowing operators to segment their audience by the events which they have performed. This opens up more targeting possiblities including the ability to respond to user interaction in real-time.

To get the most out of event-based Tribes, we needed to update a few aspects of our SDKs. Specifically we've introduced two new features:

  1. Global Events
  2. Event Metadata

Continue reading to learn how these features can help you get the most out of event-based Tribes.

Global Events#

The SDK has always offerred the ability to track events as users perform various actions. However the SDK only allowed events to be tracked at the Experience level. For customers who weren't using MTRIBES for targeting, this posed a limitation.

import { collections } from "./src/mtspace/example";
// requires an experience to track "item/clicked"let bannerExperience = collections.home.banner;bannerExperience.track("item/clicked");

To overcome this limitation we've introduced Global Events so that events can be tracked outside of an Experience. This can be done by calling Session.track() directly, without needing an Experience first.

import { session } from "./src/mtspace/example";
// ONLY requires the session to track "item/clicked"session.track("item/clicked");

This will hopefully mean a simpler setup for customers who don't require Experiences (i.e. no need to create a container Experience just to track events). For customers who are using Experiences, there is no change and everything will continue to work as normal.

Event Metadata#

The SDK enabled developers to track custom event types, however developers weren't able to provide any contextual information along with the event. For example, if you wanted to track a movie/watched event, you might want to include the title, or the genre of that movie.

videoplayer.track("movie/watched");// title ??// genre ??

To address this limitation of the SDK, we introduced Event Metadata which allows developers to provide 3 metadata pairs when tracking an event:

videoplayer.track("movie/watched", {  pair1: {    key: "title",    value: "Parasite"  },  pair2: {    key: "genre",    value: "Comedy Thriller"  },  pair3: {    key: "language",    value: "Korean"  }});

Event Metadata is particularly useful for event-based Tribes, because events can be filtered by their metadata when building a Tribe. This gives operators more granular control over which events they select for an event-based Tribe.

· 3 min read
Chris Palmer

With the introduction of our Environments feature, all MTRIBES Spaces are now available in Development, Staging, and Production variants. To complement this, we've made some changes to our SDKs and the Platform API.

Continue reading to learn about the new changes and how to upgrade to the latest SDK and Platform API.


You are now required to specify the target environment when initializing a client SDK. To do so, provide the API key associated with the target environment, found on your Space settings page.

If you haven't done so and are using the Browser SDK, an error will be logged and default fallback states will be served. If you're using Android or iOS, you will receive a compiler error.

Note: Regardless of what environment API key you specify, any fallbacks served will always be for the Production environment. Learn more about fallbacks in our SDKs.

To learn more about how to upgrade your code to use the environments feature, see the following guides:

  1. Browser
  2. iOS
  3. Android

Note: Currently, the Roku SDK does not support configuration of the target environment, so it will default to Production.

Collection publishing

You will need to ‘Publish’ any pre-existing Collections in the Staging & Development environments for them to work correctly.

Platform API V2#

The biggest difference between our Platform API V1 and V2 is the addition of the Environment Resource. There have also been some changes to the existing User Resource as users and visitors are now scoped at the environment level.

The Environment Resource lists environments available for your Space (Development, Staging or Production):

GET /v2/spaces/:spaceId/environments

The User resource has been moved to underneath the Environment resource. To manage users belonging to a particular environment, you must specify the API key for that environment in path parameters:

GET /v2/spaces/:spaceId/environments/:envKey/users

Upgrade Steps#

  1. Switch to the Platform API V2.

    Change v1.0 to v2 in the request URL.




  1. Include the environment keyword when managing users.

    For User Resource requests, include the environment keyword in the path: /environments/{production/development/staging}




  2. Manage users and visitors in different environments.

    If you wish to manage users on a different environment to production, use either staging or development as the environment keyword in the request path.




Learn more about the Platform API.

End of life#

The Platform API V1 will be deprecated by February 2022. If you still require access to this version of the API, refer to the Platform API Documentation V1.

· 2 min read
Mike Stead

We've been working hard on improving our developer CLI.

These changes are being released today, and we recommend you upgrade to take advantage of them.

OAuth sign-in#

Previously, when generating Space integration code via the CLI, you were required to enter an admin-level organization secret key.

Now, with this latest update, security is coordinated via OAuth 2. This removes the need for a shared secret, and allows you (developers) to generate code against any Space you have access to, across your organizations.

What to expect#

After upgrading, when you next run mtribes setup or mtribes update, you’ll be redirected to the MTRIBES sign-in page to authenticate. Once complete, the code generation process will be similar to before.


We'll be removing the old organization shared secret key in the coming weeks. Once removed you'll be required to upgrade the CLI to continue to generate code.

Server-side code generation#

When generating Space integration code, we populate a set of predefined templates specific to your target language. These templates were previously bundled with the CLI. While this was convenient, it also introduced some drawbacks:

  • The need to upgrade the CLI to get the latest template improvements.
  • The potential for inconsistent templates between developers using different CLI versions.

Going forward, all code generation will be done server-side, removing these issues.

What to expect#

There shouldn't be any change to code generation. These updates have been made entirely behind the scenes.

We’re continually looking for ways to improve our platform so keep an eye out for further updates.

· 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#


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 });


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.


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))


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))


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)


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.

· 2 min read
Mike Stead

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.


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.