SDK Analytics

HotMic provides a variety of events available for your team via our SDK. This allows you to get insights into how your users are interacting with our SDK inside your application. Not all users of the SDK will use the same features, so some of these events or screens may not be applicable to your usecase.

We have analytic events for each of the following categories of events:

  • Screen Shown Events - These trigger when a screen or panel/panel is displayed.
  • Video Events - These trigger whenever a video is played (from host or creator).
  • Joining a Stream Analytics Events - These trigger in relation to when a user attempts to join a stream.
  • Poll Events - These trigger when a viewer sees or acts on polls.
  • Follow/Share Events - These trigger when a viewer takes action related to following or sharing.
  • Sync Events - For TV Syncing events for syncronizing the timing with another screen.
  • Chat Events - For events relating to chats.
  • Tip Events - For events relating to tipping.
  • Error Events - For any errors that we can catch and report on.

Screen Shown Analytics Events

This following events trigger when a screen/panel is shown to the user:

  • "unknown" - If for some reason the screen can't be inferred, it will show "unknown".
  • "player" - The main screen of the SDK, which has the stream and other content.
  • "broadcaster_profile" - The profile screen for the creator.
  • "user_profile" - User profile screen shown on tapping any user thumbnail in the chat panel
  • "guest_user_profile" - User profile screen shown on tapping any user thumbnail in people section from the player screen.
  • "sync_panel" - The panel to complete TV sync.
  • "player_options_panel" - The options panel for settings in the viewer app.
  • "tips_panel" - The panel that displays when a user opts to tip.
  • "chat_options_panel - Panel displaying options (Delete, Block, Make Moderator, etc..)

Video Analytics Events

Video events whenever a video has ended for a viewer. I The videos that this affect are the creator's streamed video OR if a viewer is sending their video (using a guest call-in feature). This event will trigger when the video is over, which includes when a viewer closes the app or leaves the stream.

  • Video Played
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String
    • Video State - String
      • "scheduled" - Scheduled to start streaming at a future time.
      • "live" - Currently streaming.
      • "vod" - Ended and available for recorded viewing (VOD).
      • "ended" - Ended and not available for VOD.
    • Reason - String - Reasons can be:
      • "unknown" - if reason cannot be inferred (e.g. app crash)
      • "user" - User closed the player
      • "ended" - Stream has ended
      • "deleted" - Stream has been deleted
      • "switched" - User has switched the video to something other video
      • "signout" - User has signed out or has been logged out

Joining a Stream Analytics Events

For some users of the SDK, your users may be able to join the stream with video or Audio. Different apps may call it different things, like "Guest Call-In" or "Cameo". The below listed events all relate to that feature. If a viewer is joining with video, you can expect video events to fire in close proximity to the "join stream" events. If they are using "audio only", then the video events will not trigger.

  • Join Stream Shown
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Source - String
      • "auto" - Panel auto launched by the Player screen either on Player init or pubnub update
      • "state_change" - Panel already open, but refreshes due to status change
    • State - String - This is the "viewer's guest call in state", meaning if they have asked to join the stream to contribute by audio or video.
      • "not_requested" - The viewer has not requested to call in.
      • "pending" - The viewer has requested to call in but has not been approved
      • "approved" - The viewer has been approved to call in and is in the stream by audio or video.
      • "disabled" - The viewer's call in status has been removed by a creator or producer.
    • Host ID - String - Host id of this stream
  • Join Stream Action Tapped - When the user taps the action or cancel button on the join stream panel
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • State - String - This is the "viewer's guest call in state", meaning if they have asked to join the stream to contribute by audio or video.
      • "not_requested" - The viewer has not requested to call in.
      • "pending" - The viewer has requested to call in but has not been approved
      • "approved" - The viewer has been approved to call in and is in the stream by audio or video.
      • "disabled" - The viewer's call in status has been removed by a creator or producer.
    • Host ID - String - Host id of this stream
    • Action - String -
      • "request" - When a user requests to join a stream.
      • "cancel" - When a user cancels a request to join a stream.
      • "purchase" - When a user has purchased the ability to join a stream.
      • "go_live" - When a user actually joins a live stream.
  • Join Stream Action Success - If the requested action, for a given stage, was successfully completed.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Host ID - String - Host id of this stream
    • Action - String -
      • "request" - When a user requests to join a stream.
      • "cancel" - When a user cancels a request to join a stream.
      • "purchase" - When a user has purchased the ability to join a stream.
      • "go_live" - When a user actually joins a live stream.
  • Join Stream Action Error - On encountering error while performing the action.
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Host ID - String - Host id of this stream
    • Action - String -
      • "request" - When a user requests to join a stream.
      • "cancel" - When a user cancels a request to join a stream.
      • "purchase" - When a user has purchased the ability to join a stream.
      • "go_live" - When a user actually joins a live stream.
    • Stage - String -
      • "request"
      • "cancel"
      • "purchase"
      • "verify"
      • "consume"
    • Error Code - String - This will return the error code with a message.
    • Details - String - Any additional data that can help debug this error. Can be the server message, billing error message or any other platform param that should be logged
  • Join Stream Leave -On user leaving a join stream session. The leave can be triggered by the user manually or due to the host deleting the user from the portal.
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Source String -
      • "manual" - User tapped on the leave option
      • "host_ended" - Host has removed the user from the live guest.
  • Video Publish Init -On request of any video .
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Join State String "not_requested" | "pending" | "approved" | "live" | "disabled"
    • Mic Enabled - Boolean - True means that the user has enabled their microphone from within the OS and provided access to the SDK (via your application) to use.
    • Camera Enabled - Boolean - True means that the user has enabled their camera from within the OS and provided access to the SDK (via your application) to use.
  • Video Publish Connected -On publisher connected successfully.
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Join State - String - This is the "viewer's guest call in state", meaning if they have asked to join the stream to contribute by audio or video.
      • "not_requested" - The viewer has not requested to call in.
      • "pending" - The viewer has requested to call in but has not been approved
      • "approved" - The viewer has been approved to call in and is in the stream by audio or video.
      • "disabled" - The viewer's call in status has been removed by a creator or producer.
    • Mic Enabled - Boolean - True means that the user has enabled their microphone from within the OS and provided access to the SDK (via your application) to use.
    • Camera Enabled - Boolean - True means that the user has enabled their camera from within the OS and provided access to the SDK (via your application) to use.
  • Video Publish End - On ending the video publishing. This should be whenever a stream
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Join State - String - This is the "viewer's guest call in state", meaning if they have asked to join the stream to contribute by audio or video.
      • "not_requested" - The viewer has not requested to call in.
      • "pending" - The viewer has requested to call in but has not been approved
      • "approved" - The viewer has been approved to call in and is in the stream by audio or video.
      • "disabled" - The viewer's call in status has been removed by a creator or producer.

Poll Analytics Events

These trigger when a viewer sees or acts on polls.

  • Poll Shown - On user tapping a poll in the chat.
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Type - String - "contest"|"poll"|"leaderboard"|"winner"
  • Poll Option Tapped - On user tapping a poll in the chat.
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
  • Poll Submit Success
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Poll ID - String - The HotMic generated UUID for the poll.
    • Option ID - String - XXXX
  • Poll Logo Tapped - On tapping the logo in the poll panel
    • Video ID - String - The ID of the video in the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Link - String - sponsor url
    • Source - String
      • "contest" - The poll logo tapped from the tab introducing the contest.
      • "poll" - The poll logo tapped from the tab showing the poll.
      • "winner" - The poll logo tapped from the tab showing the winner.

Follow/Share Analytics Events

These trigger when a viewer takes action related to following or sharing.

  • Follow Tapped
    • Follow - Boolean - "true" | "false" true means the user attempted to follow
    • Broadcaster ID - String
    • Broadcaster Name - String
    • Screen - String
    • Screen Name - Refer the screen events to see the list of possible screens
  • Share Tapped - When tapping the share option.
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
  • Share App Selected
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
    • App - String - Identifier of the app selected by the user for sharing.

Sync Analytics Events

  • Sync Successful
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Offset - Double - Sync offset in seconds
    • Source - String - Where the sync was triggerred from. Refer values sheet
  • Sync Failed
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
    • Stream Type - String - "broadcast" is the only option at this time.
    • Offset - Double - Sync offset in seconds
    • Sync Error - Double - Sync error in seconds
    • Source - String - Where the sync was triggerred from. Refer values sheet
    • Reason - String - Why sync failed. Refer values sheet

Chat Analytics Events

  • Chat Sent - When a chat message is sent.
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
  • Chat Reacted - On choosing a reaction in the chat.
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
    • Value String like | fire | laugh | anger | sadness
    • Type String add | delete
  • Chat Actions
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
    • Value String make moderator | block | delete | report

Tip Analytics Events

  • Tip Tapped - On tapping the tip option
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
  • Tip Given - On paying the tip
    • Video ID - String - The ID of the video in the stream.
    • Video Title - String - The title of the stream created by the creator when setting up the stream.
    • Amount - Double
    • Currency - String - International currency abbrev. (like USD, GBP, etc...)

Error Analytics Events

  • Non Fatal - Any error/event that the client wishes to log. The error/event is not going to cause any anr or crash, however the occurence of the event might indicate issues.
    • Type - String "pubnub"|"opentok"|"exoplayer"|"branch"|"notifications"|"api"|"general"|"acr"|"other"

    • Title - String - e.g.: "Error in parsing pubnub presence"
    • Details - String - Data which helps to debug the issue

Undocumented Analytics Events and Properties

There may be analytics events that are not included in this list, or properties not listed for a given analytics event. These are experimental analytics by HotMic, and are not ready for production use. If you do see such an event that you believe would be useful, please contact HotMic.

ο»Ώ