Analytics & Telemetry

There are two tools provided for gathering data about your users and their activities. Both tools are optional if privacy is more important than data.

Analytics

Analytics data is generated from the Client XDK UI Components to report on user behaviors within your applications so that your application can chose to listen for these events and log them to the logging service of your choice.

Note

Analytics data is made available to your application so your application may log it; Layer’s XDKs do not record any analytics data locally or on Layer servers; this data is available to you alone.

The following activities are reported via Analytics Events:

  • Messages Viewed
  • Messages Clicked
  • Carousel Messages Scrolled

Messages Viewed

Messages Viewed events are triggered whenever messages are:

  • Displayed in the Message List
  • Scrolled within the Message List
  • A new messages arrives and the Message List automatically scrolls its self to the bottom
  • App changes from running in background to foreground

These analytics events will typically only occur after a message has been viewed long enough for a user to have really seen it; however, if the message is shown in its own View outside of the Message List, it may be considered as viewed as soon as it is rendered.

Name Type Description
type String “message-viewed”
size String “medium” (identifies if this message was viewed when rendered in small, medium or large format)
where String “message-list”, “layer-dialog”, div.className1.className1 etc…
message Message Message object representing the Message that was viewed
model MessageTypeModel Model representing the Message that was viewed
modelName String Name of the model that was viewed (“ProductModel”, “CarouselModel”, “TextModel”, etc…)
wasUnread Boolean True if this was the first time the message was viewed/marked as read, else False
inBackground Boolean True if the browser tab/window/etc… does not have focus/foreground (Web only)
Layer.client.on('analytics', (evt) => {
  switch (evt.type) {
    case 'message-viewed':
      console.log(`Message ${evt.message.id} and its ${evt.modelName} were seen in the
        ${evt.inBackground ? 'background': 'foreground'} and was${evt.wasUnread ? '' : ' already '}
        marked as read from the ${evt.where} UI Component`);

      myLogger({
        mesage: evt.message.id,
        eventType: 'message-viewed',
        messageType: evt.modelName,
        where: evt.where
      });
      break;
  }
});

Messages Selected

Messages Selected events are triggered whenever messages are:

  • Displayed in the Message List and tapped/clicked within the Message List
  • Displayed outside of the Message List and tapped/clicked
  • Currently these are not reported when the user has navigated to a Large Message Viewer and then tapped/clicked on the message in the Viewer

Note

Even messages that have no actions associated with them (such as a simple textual message) are reported on when the user selects them

Name Type Description
type String “message-selected”
size String “medium” (identifies if this message was viewed when rendered in small, medium or large format)
where String “message-list”, “layer-dialog”, div.className1.className1 etc…
message Message Message object representing the Message that was selected
model MessageTypeModel Model representing the Message that was selected
modelName String Name of the model that was selected (“ProductModel”, “CarouselModel”, “TextModel”, etc…)
actionEvent String Name of the action to fire for this Model (typically the default action unless one was provided in the message)
actionData Object Any action data parameters associated with this message / model
Layer.client.on('analytics', (evt) => {
  switch (evt.type) {
    case 'message-selected':
      console.log(`Message ${evt.message.id} clicked/tapped and its ${evt.modelName}
        triggered ${evt.actionEvent}`);

      myLogger({
        mesage: evt.message.id,
        eventType: 'message-selected',
        messageType: evt.modelName,
        where: evt.where,
        action: evt.actionEvent,
      });
      break;
  }
});

Carousel Messages present a collection of items. Knowing that users are scrolling through these items may help you understand more about what users are doing with your Carousels. Carousel Scroll Events:

  • Report what items were previously visible
  • Report what items are now visible

Note

For desktop web browsers, it may be the case that all items of a carousel can be rendered without scrolling, in which case users may have viewed all carousel items without any Carousel Scrolled Events.

Name Type Description
type String “carousel-scrolled”
size String “medium” (identifies if this Carousel Message was viewed when rendered in small, medium or large format)
where String “message-list”, “layer-dialog”, div.className1.className1 etc…
message Message Message object representing the Message that was selected
model MessageTypeModel Model representing the Message that was selected
newItems Object[] Array of information about Carousel Items showing after scrolling
newItems.model MessageTypeModel Models for the items scrolled into view
newItems.part MessagePart Message Part for the items scrolled into view
oldItems Object[] Array of information about Carousel Items showing before scrolling
oldItems.model MessageTypeModel Models for the items visible prior to scrolling
oldItems.part MessagePart Message Part for the items visible prior to scrolling

NOTE

oldItem may contain items that are still visible after scrolling; it does not represent items that were removed from the list, but rather the set of previously visible items some of which may still be visible.

Layer.client.on('analytics', (evt) => {
  switch (evt.type) {
    case 'carousel-scrolled':
      console.log(`Carousel Message ${evt.message.id} now showing
      ${evt.newItems.map(item => item.model.getModelName() + ': ' + item.part.id).join(', ')}`);

      myLogger({
        mesage: evt.message.id,
        eventType: 'carousel-scrolled',
        where: evt.where,
        oldItems: evt.oldItems.map(item => item.part.id),
        newItems: evt.newItems.map(item => item.part.id),
      });
      break;
  }
});

Telemetry

Layer Clients collect telemetry data to better understand how the SDKs are used, what actions users are taking, and what performance those users are observing. No Personally Identifiable Information is collected, and telemetry can be disabled if desired.

What you should know about this data:

  • No user identifiable data is tracked; no user_ids, names, message content, conversation metadata, nor any data about whom you are having conversations with
  • We do track:
    • how many messages are sent
    • how many conversations are created
    • how many authentications/deauthentications
    • how many queries are fired, and whether those queries are on Messages, Conversations, Identities, Announcements, etc.
    • how many syncs are performed by the device
    • how quickly each of the above activies were performed

This data will allow us to better tune our services for performance, and to better model and optimize based on how users are using our services. In the future, it will also be made available to Layer’s customers so they can better analyze how their apps are being used.

Telemetry can be disabled:

Layer.init({
    appId: "layer:///apps/staging/YOUR-APP-ID",
    telemetryEnabled: false
});
Privacy UI Concepts