Integrations & SDKs
iOS SDK

HotMic offers an iOS SDK so you can let users inside your application watch your streams. This allows you to drive users to your own application, to retain control over your users, unlike in Twitch and Facebook, 
To learn more, we recommend looking at our Sample App, which is the fastest way to see the iOS SDK in action inside a sample application. 
Then, we recommend reviewing our SDK Installation Guide, found here: iOS SDK Installation Guide﻿ 
iOS Sample App
HotMic offers a sample app to see how to use our iOS SDK in your application. Here is a step-by-step guide to downloading and running the HotMic SDK sample applications for iOS.
Requirements
A link to the HotMic SDK sample application provided by HotMic.
An API Key provided by HotMic.
A JWT token created using a Secret provided by HotMic. Instructions for how to create the token can be found below.  
A white labeled production dashboard where you will produce streams.  
Authentication with JWT Token
For security, when using the SDK your app controls authentication with a JWT Token, which you pass to HotMic.
JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties. - jwt.io﻿
You will receive an API Secret from HotMic, which you will use to create the token.  The token will be used to authenticate the user, as well as provide information such as their name, an avatar, a unique ID, or another information which is needed by the SDK. 
This is the expected format of the JWT token:
JS
// nodejs example
const jwt = require('jsonwebtoken');
accessToken = jwt.sign({identity: {
    user_id: user.id, // Should be consistent for the user (uuid4)
    display_name: user.display_name, // Name displayed in chat/profiles
    profile_pic: user.profile_pic, // Image URL (https://ui-avatars.com/api/?name=Test&background=0DCAD6&color=fff)
 }}, [API SECRET], { expiresIn: '7d'})
// nodejs example
const jwt = require('jsonwebtoken');
accessToken = jwt.sign({identity: {
    user_id: user.id, // Should be consistent for the user (uuid4)
    display_name: user.display_name, // Name displayed in chat/profiles
    profile_pic: user.profile_pic, // Image URL (https://ui-avatars.com/api/?name=Test&background=0DCAD6&color=fff)
 }}, [API SECRET], { expiresIn: '7d'})
﻿
Note, the user_id field should be consistent for each invocation of the SDK for that particular user. 
Quick Steps to Generate a JWT Token Online
You can also generate JWT tokens online! This is good for test purposes while getting started, or to use the sample app. Here is one way to do it. We do not recommend using this method with any sensitive data.
Go to https://jwt.io/﻿ and scroll down add a payload like the following into the "Payload" section. Paste your secret into the "Verify Signature" section. This screenshot shows how it looks:
﻿
And here is a sample payload that should work for your application:
JSON
{
  "identity": {
    "user_id": "3d5567c2-603c-4b08-b917-7e9f05c8ebb5",
    "display_name": "tester1",
    "profile_pic": "https://ui-avatars.com/api/?name=test&background=0DCAD6&color=fff",
    "badge": "https://hotmic-content.s3.us-west-1.amazonaws.com/badges/10_badge.png?c251fece-c08f-48a0-931e-70cfe8ea7ed4"
  },
  "iat": 1657658555,
  "exp": 1821724014
}
{
  "identity": {
    "user_id": "3d5567c2-603c-4b08-b917-7e9f05c8ebb5",
    "display_name": "tester1",
    "profile_pic": "https://ui-avatars.com/api/?name=test&background=0DCAD6&color=fff",
    "badge": "https://hotmic-content.s3.us-west-1.amazonaws.com/badges/10_badge.png?c251fece-c08f-48a0-931e-70cfe8ea7ed4"
  },
  "iat": 1657658555,
  "exp": 1821724014
}
﻿
Then copy the code from the "Encoded" section of this page, and use that in the sample app. 
iOS Installation
Unzip the HotMicMediaPlayerSample.zip file, and open MediaPlayerSample.xcworkspace in xCode.
Open MediaPlayerSample/AppDelegate, and update apiKey and accessToken, inside the call to HMMediaPlayer.initialize.
Install CocoaPods, and run pod install from the terminal in the MediaPlayerSample folder .
Choose your target device or simulator in Xcode, and press Run
You should see a few streams populate in the app.  Tap on one of them to load the media player. 
See the installation guide for a more detailed description of the SDK.
Use the Production Dashboard to create and start streams.  You can use the account ios-test1@hotmic.io/password to login, or sign up for a new account.
﻿
iOS SDK Installation
Here are instructions on how to install the iOS SDK. If you ever have issues installing the iOS SDK, please contact our team.
The name of our SDK is HotMicMediaPlayer. HotMicMediaPlayer allows you to integrate the HotMic player experience into your app. Use this framework to create a HMPlayerViewController for a specific stream and present it full screen.
Requirements
API Key and JWT Secret: Will be provided by HotMic.
iOS 12+
iPadOS user interface is not tailored to the iPad, its just a larger iPhone view. A future update will expand tablet support.
macOS apps are not supported.
Swift UIKit app
Integration in Objective-C or SwiftUI apps is not officially supported
App is already live on the App Store
HotMicMediaPlayer uses the UIWebView framework for YouTube playback. Apple does not allow new apps to use UIWebView. The reason UIWebView is used is due to the fact that WKWebView does not support all features needed for YouTube playback. This component can also be removed if YouTube playback is not required for your use-case.
App uses view controller based status bar appearance.
App supports portrait and landscape orientations.
App disables Bitcode
Because HotMicMediaPlayer uses ACRCloud which was built without full Bitcode support, HotMicMediaPlayer must disable Bitcode, and your app must as well
﻿
Accessibility
Accessibility support including Dynamic Type, VoiceOver, Switch Control, etc
Default system colors provide high contrast variants
Dynamic Type support respects the device text size settings
Large content viewer is supported for small icon buttons
Views are marked as accessibility elements appropriately
Accessibility traits are set to identity headings, buttons, selection state, etc
Accessibility labels are added to ensure controls are titled
Accessibility hints are added where additional instruction is helpful 

App Privacy
When integrating HotMicMediaPlayer into your app, you must disclose the data it and its dependencies collect on the App Store:
Name - used for product personalization
Audio data - used for app functionality
Device ID - used for analytics
Advertising data - used for developer’s advertising or marketing, analytics, linked to the user’s identity
Other diagnostics data - used for app functionality, linked to the user’s identity
HotMicMediaPlayer has the following dependencies:
ACRCloudSDK
BitmovinPlayer
TrueTime
OpenTok
PubNub
FittedSheets
Kingfisher
If your team is already using 1 or more of these dependencies, please contact us so we can ensure to get you the right version of the HotMicMediaPlayer SDK that matches your dependencies.
CocoaPods
Add the following to your Podfile, then run pod repo update and then pod install
Swift
platform :ios, '12.0'

use_frameworks!
source 'https://cdn.cocoapods.org/' # Default global repository
source 'https://github.com/bitmovin/cocoapod-specs.git'
target 'YourAppTarget' do
  pod 'HotMicMediaPlayer', podspec: 'https://.../HotMicMediaPlayer.podspec'
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end
platform :ios, '12.0'

use_frameworks!
source 'https://cdn.cocoapods.org/' # Default global repository
source 'https://github.com/bitmovin/cocoapod-specs.git'
target 'YourAppTarget' do
  pod 'HotMicMediaPlayer', podspec: 'https://.../HotMicMediaPlayer.podspec'
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end
﻿
Privacy
Add the following keys to your target’s Info tab:
NSCameraUsageDescription - this is required to join the room with video
NSMicrophoneUsageDescription - this is required to join the room with audio and sync the stream with a TV
Capabilities
Add the following capabilities to your app’s target:
Background Modes - Audio, AirPlay, and Picture in Picture
In-app Purchases
HotMic supports two types of in-app purchases in the player experience: tip the host and join the stream. You can support these in your app as well. You will need to configure these in App Store Connect, then be sure to submit them to Apple for review alongside your app update.
API Key and Authorization Token
You will need an API key for your app to use the HotMic service. You will also need to create an authorization token. HotMic will provide you with the key and information on how to create the token in the appropriate format.  
Initialization
Initialize HMMediaPlayer with your API key and authorization token. This must be done before any other functions are called in HMMediaPlayer, so we recommend performing initialization in your AppDelegate’s didFinishLaunchingWithOptions. If needed, it can be called again later, for example if the token changes.
Swift
import HotMicMediaPlayer
HMMediaPlayer.initialize(apiKey: "YOUR_KEY", accessToken: token)
import HotMicMediaPlayer
HMMediaPlayer.initialize(apiKey: "YOUR_KEY", accessToken: token)
﻿
ApiKey
A UUID provided by HotMic. 
AccessToken
Use any JWT library to create a token.  Format is as follows:
JS
const accessToken = jwt.sign({identity: {
    user_id: [Consistent ID for user],
    display_name: user.display_name,
    profile_pic: user.profile_pic,
  }}, apiSecret, { expiresIn: '1d'})
const accessToken = jwt.sign({identity: {
    user_id: [Consistent ID for user],
    display_name: user.display_name,
    profile_pic: user.profile_pic,
  }}, apiSecret, { expiresIn: '1d'})
﻿
Get Streams
Streams are returned in reverse chronological order. You can fetch streams from HotMic with the following filters:
that are live, scheduled, and/or video-on-demand replays. 
userID: the userid you want to filter the streams by:
Type: string
Default: NULL (all possible streams)
limit: The max number of streams to return
Type: integer
Example: 40
Default: 30
skip: The number of results to skip you want to not return in the results, typically used for pagination.
Type: integer
Example: 10
Default: 0
﻿
JS
HMMediaPlayer.getStreams(live: true, scheduled: true, vod: true, userID: nil, limit: nil, skip: nil) { result in
    switch result {
    case .success(let streams):
        // Display the list of streams

    case .failure(let error):
        // Handle error
    }
}
HMMediaPlayer.getStreams(live: true, scheduled: true, vod: true, userID: nil, limit: nil, skip: nil) { result in
    switch result {
    case .success(let streams):
        // Display the list of streams

    case .failure(let error):
        // Handle error
    }
}
﻿
Player View Controller
Initialize a HMPlayerViewController and present it:
﻿
Swift
let playerViewController =  HMMediaPlayer.initializePlayerViewController(
    streamID: streamID, 
    delegate: self, 
    supportsMinimizingToPiP: true
)
present(playerViewController, animated: true, completion: nil)
let playerViewController =  HMMediaPlayer.initializePlayerViewController(
    streamID: streamID, 
    delegate: self, 
    supportsMinimizingToPiP: true
)
present(playerViewController, animated: true, completion: nil)
﻿
Setting the modalPresentationStyle to a value other than fullScreen is not allowed.
The player view controller is presented in portrait mode, then after presentation it will support rotating to landscape. Note that the player may force rotate to portrait in the experience, for example, if a tall sheet needs to be presented.
Player View Controller Delegate
Implement the HMPlayerViewControllerDelegate protocol to support functionality of the player screen.
When the user is finished with the player experience, for example when they tap a button to close the screen, the following function is called allowing you to dismiss it. A PiP view may be provided which allows you to place it into a custom Picture-in-Picture window, such as one provided by the PIPKit library. If you’d like to support PiP, initialize a player view controller with supportsMinimizingToPiP: true, then store this view controller in a strongly held property to prevent it from deinitializing. When you wish to restore the player full-screen, provide the player view to move back into the player view controller then present it again. Be sure to set the view controller property to nil when the user wishes to close the player or PiP.
func playerViewController(_ viewController: HMPlayerViewController, didFinishWith pipView: UIView?) {
    dismiss(animated: true, completion: nil)
    
    if let pipView {
        let pipViewController = PIPViewController()
        pipViewController.addContentView(pipView)
        PIPKit.show(with: pipViewController)
    } else {
        if PIPKit.isActive {
            PIPKit.dismiss(animated: true) {
                self.playerViewController = nil            }
        } else {
            playerViewController = nil        }
    }
}
Each time a player is needed, the following function is called allowing you to provide a custom player that implements the HMPlayer protocol. Return nil if you'd like to use the default player.
func playerViewController(_ viewController: HMPlayerViewController, playerForAssetAt url: URL) -> HMPlayer? {
    return nil}
Player View Controller Functions
To support returning to the full-screen player experience from Picture-in-Picture, call HMPlayerViewController’s restorePiPView(_:) function and then present the player view controller full screen.
func pipViewControllerDidTapFullScreen(_ viewController: PIPViewController) {
   guard let playerViewController else { return }
   
   playerViewController.restorePiPView(viewController.contentView)
   
   PIPKit.dismiss(animated: true)
   
   present(playerViewController, animated: true, completion: nil)
}
To show a banner ad in the player screen, call HMPlayerViewController’s displayBannerAd(withView:duration:delay:) function. Provide any UIView to display. The view fills the screen width and needs to have a known height such as an intrinsic content size or an Auto Layout constraint that defines a constant height or aspect ratio. If you do not specify a duration of time to display the ad, it will be displayed until you hide it. If you do not specify a delay, it will be displayed immediately. If you do not specify an animationDuration, a default value will be used. If you specify animationDuration: 0, it will not animate.
func displayAd() {
   let imageView = UIImageView()
   imageView.contentMode = .scaleAspectFill   imageView.isUserInteractionEnabled = true   imageView.addGestureRecognizer(UITapGestureRecognizer(target: self, action: #selector(bannerAdTapped(_:))))
   imageView.image = UIImage(named: "ad")
   imageView.translatesAutoresizingMaskIntoConstraints = false   imageView.heightAnchor.constraint(equalTo: imageView.widthAnchor, multiplier: 3.0/8.0).isActive = true   playerViewController.displayBannerAd(withView: imageView)
}
To remove the banner ad from the player screen, call HMPlayerViewController’s hideBannerAd() function. If you do not specify an animationDuration, a default value will be used. If you specify animationDuration: 0, it will not animate.
func removeAd() {
   playerViewController.hideBannerAd()
}
User Profile Delegate
To support user profile functionality, you can implement the HMMediaPlayerUserProfileDelegate protocol. If you do not implement this delegate, profile info will be obtained by HotMic rather than your app, and buttons such as follow/unfollow will not be available.
HMMediaPlayer.userProfileDelegate = self
When a user's profile info is to be shown, the following function is called allowing you to provide that user's information. Provide a success result with an HMUserProfile containing information such as their name, profile pic, followers count, following count, if they're following the current user, and if they're followed by the current user. Provide nil for any values that are unavailable. For example, if followingCount is nil the number of people this user follows will not be shown, and if followedByMe is nil the follow/unfollow button will not be shown. Or provide a success result with nil if you would like the profile info to be provided by HotMic rather than your app. Provide a failure result with an Error if one occurred.
func getUserProfile(for id: String, restriction: String?, isHost: Bool, isCohost: Bool, completion: @escaping (Result<HMUserProfile?, Error>) -> Void) {
    // Fetch the profile info and call completion}
The restriction returned should be null or view_and_polls_only, depending on whether the user is restricted.
When the user taps the follow/unfollow button, the following function is called allowing you to record the new following state. Provide an Error to the completion handler if one occurs.
func setFollowingUser(id: String, following: Bool, completion: @escaping (Error?) -> Void) {
    // Record the new state and call completion}
When the user profile is shown, the following function is called allowing you to specify whether the See Full Profile button should be shown.
func shouldShowSeeFullProfileButton(for id: String) -> Bool {
    return true}
When the user taps the See Full Profile button, the following function is called allowing you to handle this action, for example by presenting a view controller.
func seeFullProfileButtonTapped(for id: String, in viewController: UIViewController) {
    // Show the full profile}
﻿
Example of HMUserProfile:

HMUserProfile(
    name: "Test User",
    displayName: "testuser1",
    profilePic: nil,
    badge: nil,
    bio: "Hello and welcome to my user profile.",
    instagramHandle: "testuser1",
    tikTokHandle: "testuser1",
    twitchHandle: "testuser1",
    twitterHandle: "testuser1",
    youTubeHandle: "testuser1",
    followersCount: 100,
    followingCount: 50,
    followingMe: false,
    followedByMe: true
)
In App Purchase Delegate
To support tipping hosts and joining their streams for a price, you can implement the HMMediaPlayerInAppPurchaseDelegate protocol and integrate it with your StoreKit in-app purchase code. If you do not implement this delegate, users cannot tip hosts, but can still join the host for free.
Swift
HMMediaPlayer.inAppPurchaseDelegate = self

HMMediaPlayer.inAppPurchaseDelegate = self
﻿
When the user opens the tip sheet, the following function will be called to get the SKProducts available to purchase for a host ID. Your app should fetch the products that are applicable to this host from the App Store.
Swift
func getTipProducts(hostID: String, completion: @escaping (Result<[SKProduct], Error>) -> Void) {
    // Fetch the products and call completion
}
func getTipProducts(hostID: String, completion: @escaping (Result<[SKProduct], Error>) -> Void) {
    // Fetch the products and call completion
}
﻿
When the user wishes to purchase a tip, the following function will be called. Your app should initiate the in-app purchase process. If the purchase is successful, your app should then submit the tip purchase information including the App Store receipt via HMMediaPlayer’s submitTipPurchase function. HotMic will verify this purchase is legitimate and record the tip if validated. Be sure to provide an error if one occurs in this process, such as if the device cannot make payments, a purchase is already in progress, the transaction was canceled, the transaction failed, failed to get transaction info, no purchase info was found, failed to verify, or failed to process. The completion handler allows you to specify if you want this error’s localizedDescription to be shown to the user and if a button should be provided to retry submitting their purchase information if that request fails. We strongly recommend persisting the purchase information on the device and avoid marking the SKPaymentTransaction finished until the purchase has been successfully submitted, as this allows you to retry submitting the information when StoreKit informs you there is a not-yet-finished purchased transaction.
Swift
func purchaseTip(
  product: SKProduct, 
  userID: String, 
  hostID: String, 
  streamID: String, 
  message: String?, 
  anonymous: Bool, 
  completion: @escaping ((error: Error?, showError: Bool, canRetry: Bool)) -> Void) {
    // Purchase the product then call HMMediaPlayer.submitTipPurchase to record it, 
    // or provide an error
}
func purchaseTip(
  product: SKProduct, 
  userID: String, 
  hostID: String, 
  streamID: String, 
  message: String?, 
  anonymous: Bool, 
  completion: @escaping ((error: Error?, showError: Bool, canRetry: Bool)) -> Void) {
    // Purchase the product then call HMMediaPlayer.submitTipPurchase to record it, 
    // or provide an error
}
﻿
When the user wishes to retry submitting their purchase information, the following function will be called. Your app should look up the purchase information with the provided product identifier and submit it via HMMediaPlayer’s submitTipPurchase function.
Swift
func retrySubmittingPurchaseInfo(
  productID: String, 
  completion: @escaping ((error: Error?, showError: Bool, canRetry: Bool)) -> Void) {
    // Call HMMediaPlayer.submitTipPurchase to try recording it again
}
func retrySubmittingPurchaseInfo(
  productID: String, 
  completion: @escaping ((error: Error?, showError: Bool, canRetry: Bool)) -> Void) {
    // Call HMMediaPlayer.submitTipPurchase to try recording it again
}
﻿
To support join stream in-app purchases, very similar functions as those for tips are available and should be used in the same way.
If you reach out to us we would be happy to provide you with more information and example code from our in-app purchase manager that will allow you to implement this the same way we did.
Analytics Event Observing
To be notified of analytics events as they occur throughout the experience, you can implement the HMMediaPlayerAnalyticsEventObserving protocol. Documentation for event names and info keys and values is not yet available.
﻿
Swift
HMMediaPlayer.analyticsObserver = self

func eventStarted(name: String) {
    // Start timing this event by name
}

func eventOccurred(name: String, info: [String: Any]) {
    // Stop timing event by name, maybe record the event
}
HMMediaPlayer.analyticsObserver = self

func eventStarted(name: String) {
    // Start timing this event by name
}

func eventOccurred(name: String, info: [String: Any]) {
    // Stop timing event by name, maybe record the event
}
﻿
﻿
Updated 24 Aug 2023
Using Your Own Player (Android)
Using Your Own Player (iOS)
iOS SDK

iOS Sample App

Requirements

Authentication with JWT Token

Quick Steps to Generate a JWT Token Online

iOS Installation

iOS SDK Installation

Requirements

﻿

Accessibility

App Privacy

CocoaPods

Privacy

Capabilities

In-app Purchases

API Key and Authorization Token

Initialization

ApiKey

AccessToken

Get Streams

Player View Controller

Player View Controller Delegate

Player View Controller Functions

User Profile Delegate

In App Purchase Delegate

Analytics Event Observing
