Integrations & SDKs

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_panel" - This panel contains all the users chat, typically below the video in portrait mode.
  • "chat_options_panel - Panel displaying options (Delete, Block, Make Moderator, etc..)
  • "expanded_chat" - This popup is for when a user taps a comment to react to it, they see reaction options such as 👍 .
  • "people_panel" - This panel shows when you tap the "people" icon in the bottom left next to chat. It typically lists the number of people in the stream.

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 Started This occurs any time we start playing video. This can occur when a user taps play on a video (VOD or Live), or when a user enters a stream with a video that automatically plays, when the user resumes a paused stream, or when there is an issue that causes the player to stop and then restart. It is possible in some cases for the "Video Played" event to trigger without the user having started the video, if they left before playing a video.
  • 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
    • Duration - Double - The number of seconds a particular viewer was viewing a video that was playing. Duration:
      • Starts incrementing when the user starts watching any video in the stream.
      • Stops incrementing when they are no longer watching video (for example, if they paused the video).
      • Will resume incrementing if the video is started again while in the same session.
      • Is not cumulative between sessions. If they leave and come back, when they come back duration will count again from 0.
      • Increments regardless if the video is in a VOD or LIVE state.
      • Example: So if a user comes into a stream, waits for 10s for the video to start, watches the video for 20s, then leaves. Duration should return 20s. If they come back to the stream and watch another 50s, it should return 50s. If they come back the next day and watch 4000s of VOD, it should return 4000.0s.

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 - Share Tapped is logged any time a button is tapped which brings up the share sheet.
    • 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 - Share App Selected is logged when the user successfully shares - eg they tapped Messages and sent that share text to someone. The App parameter tells you which app they shared it to.
    • 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
    • ID - String - The ID of the stream
    • Action - 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.

Updated 14 Feb 2023
PREVIOUS
Custom Themes
NEXT
Single Sign-On (SSO) (BETA)
Docs powered by Archbee