Teak Features

Login

Teak’s functionality depends on knowing when a user plays and on what device they play.

At every game launch, send the player’s ID to Teak using teak.login().

Example

// ...
const additionalData = {};
teak.login(YOUR_PLAYER_ID, additionalData);

Make sure that your user ID is a unique ID for the player in your game.

What Player ID should you use?

Your game probably has a user ID to store progress, coin balances, and other useful data. Use that ID with Teak too.

It should be uniquely identify the current user.
Ideally the same ID that is used in your game’s backend.
Send it as early as possible in the game’s lifecycle.

Having a consistent ID between your game makes customer support easier, and makes life easier for your analytics team.

User Configuration

Additional data, such as a player’s email address and Facebook ID, can be passed to Teak by setting the appropriate fields on the additionalData object passed to teak.login().

If you need to update any of this additional data during a game session, call teak.login() with an appropriately configured additionalData object. teak.login() will never clear or remove information about a player, and fields that are not set on the additionalData object will be ignored.

Providing Additional Data Example

// ....
const additionalData = {
  email: YOUR_PLAYER_EMAIL,
  facebookId: YOUR_PLAYER_FACEBOOK_ID
};

teak.login(YOUR_PLAYER_ID, additionalData);

Rewards

Whenever your game should grant a reward to a player Teak will let you know by sending out an event to all listeners added to teak.on("reward").

Teak does not provide any in-game UI to inform a player if they received a reward or not. You should add a listener to teak.on("reward") which detects if the reward was granted or denied, and informs the player what happened.

This callback will be concurrent with the Teak Reward Endpoint server to server call.

Example Reward Listener

function handleReward(rewardEvent) {
  switch(rewardEvent.status) {
    case teak.RewardStatus.GrantReward:
      for (const [rewardId, amount] of Object.entries(rewardEvent.reward)) {
        console.log(`Granted player ${amount} of ${rewardId}`);
      }
      break;
    case teak.RewardStatus.Expired:
      console.log("The reward has expired");
      break;
    case teak.RewardStatus.AlreadyClaimed:
      console.log("You already claimed this reward!");
      break;
    case teak.RewardStatus.TooManyClaims:
      console.log("Too many other players already claimed this reward");
      break;
    case teak.RewardStatus.SelfClaim:
      console.log("You can't claim your own reward!");
      break;
    case teak.RewardStatus.ExceedMaxClaimsForDay:
      console.log("You've already claimed too many rewards today");
      break;
    case teak.RewardStatus.NotForYou:
      console.log("This reward is restricted to a different player");
      break;
    case teak.RewardStatus.InvalidReward:
      console.log("The reward id was not recognized");
      break;
  }
}

teak.on("reward", handleReward);

Request Notification Permissions

To use Web Push you are required to ask the player if you can send them notifications. Do that with the teak.registerForNotifications() call.

Permissions Example

// ...
teak.registerForNotifications(true, (notificationState) => {
  console.log("Web Push is " + notificationState);
});

You can still make this call even if the player cannot be prompted for permissions again. In that case the callback will be called with the current notification state.

Due to the nature of Web Push, each player may only be registered to a single Web Push vendor at a time. The first parameter to registerForNotifications(), switchVendor, indicates if you would like Teak to switch the player to use Teak for Web Push if required. When set to true, Teak will unsubscribe the player from their previous Web Push vendor and subscribe them to Web Push from Teak. This parameter has no impact if you have not used another Web Push vendor.

Local Notifications

Local Notifications let you schedule push notifications directly from your game code for the current player. This differs from Standard push notifications, which your marketing team schedules for delivery in the Teak Dashboard.

Common use cases include informing players that their hourly bonus is ready or that a tournament is over.

Use Local Notifications when you need deeply personalized content or scheduling that the game code is better equipped to determine.

For example, an hourly bonus should be a local notification scheduled by the game, since the game will know when the hourly bonus was last claimed, and when the next bonus will be ready.

A daily bonus should be setup using a standard notification scheduled in the dashboard, since the timing is not specific to the game logic.

You should not use Local Notifications for a new player flow/new user experience or lapsing player flow. Instead, your marketing team should create Triggered Schedules for these use cases.

Although you can schedule Local Notifications in your game code, you will still coordinate with your marketing team on content created on the Teak Dashboard. Discuss and document when your game triggers Local Notifications thoroughly so your marketing team can craft the most relevant messaging.

Setup a Local Notification

Before sending, you must configure the corresponding Local Schedule on the Teak Dashboard. Doing so gives you the full benefit of Teak’s analytics, A/B testing, and Content Management System when using local notifications.

The Name you give the Schedule is the first parameter for any local notification scheduling calls. Your marketing team may already have set up some Local Schedules; be sure to ask them if they have and what names they’ve given the Local Schedules.

Schedule a Local Notification

To schedule a notification from your game, use the teak.scheduleNotificationWithPersonalization(scheduleName, delayInSeconds, personalizationData) call.

scheduleName should be the name of a Local Schedule on the Teak Dashboard.

The personalizationData parameter allows you to provide custom data that can be templated into each send using Local Notification Tags. Be sure to inform your marketing team what data you send under which keys so that the tags can be properly configured.

Example Local Notification Scheduling

// Requires a Local Schedule on the Teak Dashboard with the Name "hourly_bonus"!
teak.scheduleNotificationWithPersonalization("hourly_bonus", 3600, { "coins": 100000}, (response) => {
  if(response.status === "ok") {
    console.log("Scheduled local notification to send in one hour");
  }
});

Canceling a Local Notification

To cancel a previously scheduled notification, use teak.cancelNotification(scheduleName).

Example

teak.cancelNotification("hourly_bonus", (response) => {
  if(response.status === "ok") {
    console.log("Canceled hourly bonus notification");
  }
})

Canceling all Local Notifications

To cancel all previously scheduled local notifications, use teak.cancelAllNotifications().

This call is processed asynchronously. If you immediately call teak.scheduleNotificationWithPersonalization() after calling teak.cancelAllNotifications() it is possible for your newly scheduled notification to also be canceled. We recommend waiting until the callback has fired before scheduling any new notifications.

Example

teak.cancelAllNotifications((response) => {
  if(response.status === "ok") {
    console.log("Cancelled all local notifications");
  }
});

Player Properties

Player Properties are strings or numbers associated with each player of your game in Teak. Player Properties have several uses, including

Targeting players for a send by using the player properties Audience rule
Personalizing push notification content using custom tags
Personalizing email content using custom tags
Personalizing deep links from Links, push notifications, and emails to take players to a meaningful location in your game

You do not need to register the property in the Teak Dashboard prior to sending them from your game, however you will need to register them in the Teak Dashboard before using them in targeting. Only Player Properties set to permit client updates can be updated through the SDK. Player Properties set to permit server updates may only be updated through the Server API.

Number Property

To set a number property, use: window.teak.setNumberAttribute(name, value).

Example

teak.setNumberAttribute("coins", new_coin_balance);

Number Player Properties can store values between -999999999999999999999999999.999999999 and 999999999999999999999999999.999999999.

String Property

To set a string property, use: window.teak.setStringAttribute(name, value).

Example

teak.setStringAttribute("last_slot", "amazing_slot_name");

String Player Properties can store up to 16,384 unicode characters (including emoji).

Custom Analytics Events

Teak tracks a number of analytics event by default, including install, session start, notification clicks, link clicks, and session timing, and nothing extra is needed to track them.

Teak can also track custom analytics events which can then be used for targeting. === Event Format

Teak events are a tuple of values, 'action', 'object type' and 'object instance'. For example: ['LevelUp', 'Fishing', '13'].

Object instance, and object type are optional, but if you provide an object instance, you must also provide an object type, for example ['FishCaught', null, '13'] is not allowed, but ['FishCaught', 'Salmon'] is allowed.

Tracking an Event

To track that an event occurred, use: teak.incrementEvent()

Examples

teak.incrementEvent("coin_sink", "slot", "Happy Land Slots", 25000);
teak.incrementEvent("spin", "slot", "Happy Land Slots", 1);
teak.incrementEvent("coin_source", "slot", "Happy Land Slots", 1000000);

Deep Links

Deep Links are a way to link to specific screens in your game that will open when the game is launched from a notification or Universal Link.

These are useful for promoting new content or linking directly to sale content in the game.

For the marketing team to use Deep Links, they will have to add the URL to their notifications in the dashboard. So, keep a master list of active deep links that can be shared with your team, so everyone knows what is available for use.

Deep Linking with Teak is based on routes, which act like URLs. Route patterns may include named parameters, allowing you to pass in additional data.

Add routes using: teak.registerRoute().

You need to register your deep link routes before you call teak.login().

Example

teak.registerRoute("/store/:sku", "Store", "Open the store to the given SDK", (parameters) => {
  // Any URL query parameters or path parameters will be in the parameters object
  console.log(`Open the store to this SKU: ${parameters.sku}`);
});

How Routes Work

Routes work like URLs where parts of the path can be a variable. In the example above, the route is /store/:sku. Variables in the path are designated with :. So, in the route /store/:sku there is a variable named sku.

This means that if the deep link used to launch the app was /store/io.teak.test.dollar was used to open the app, it would call the function and assign the value io.teak.test.dollar to the key sku in the dictionary that is passed in.

This dictionary will also contain any URL query parameters. For example:

/store/io.teak.test.dollar?campaign=email

In this link, the value io.teak.test.dollar would be assigned to the key sku, and the value email would be assigned to the key campaign.

When Are Deep Links Executed

Deep links are passed to an application as part of the launch. The Teak SDK holds onto the deep link information and waits until your app has finished launching, and initializing. Deep links will be processed when your game calls teak.login()

Using Deep Links

A Deep Link route may be added to any notification or email in the Advanced section when setting up a Message or Link. We recommend documenting what routes are implemented and how to use them, with examples, for your marketing team to add to notifications, emails, and links.

What is the Purpose of Another Router?

Teak uses its own internal deep link router instead of directly navigating the browser to a different URL in order to

Support personalized deep links from Link clicks, which require a call to teak.login() before they can be personalized
Support games which may not have a router
Provide a unified configuration experience for games which have native mobile apps and a desktop web experience

Session Attribution

Each time your game launches, Teak will pass all of the attribution data it has for the launch, if available, to all listeners added to teak.on("postLaunchSummary").

This callback will be called after your game calls teak.login(), and is primarily intended to assist in reporting session attribution to other analytics systems.

Example PostLaunchSummary Listener

function handlePostLaunchSummary(launchSummary) {
  if(!launchSummary.channelName) {
    console.log("Launch not attributed to a Teak source");
    return;
  }

  console.log(`Launch attributed to ${launchSummary.channelName}`);
  console.log(`Launch came from a click on ${launchSummary.creativeName}`);
  console.log(`Launch was ${launchSummary.rewardId ? "not" : ""} rewarded`);
}
teak.on("postLaunchSummary, handlePostLaunchSummary");

See PostLaunchSummaryEvent for more details.