StadiumVision Mobile (SVM) > Learn > SDK Best Practices

Cisco StadiumVision Mobile SDK Best Practices

Apple iOS

Consider the following best practices when developing and delivering an app for Apple iOS:

Correlating Reporter Data to a Specific Device

  • Apple does not permit applications to access any device information that can be used to identify that device or its owner. As a result, the iOS SDK is unable to include the MAC address in the periodic stats that it sends to the Cisco StadiumVision Mobile Reporter. As a substitute for the MAC address, the SDK instead includes a SVM Device UUID (universally unique identifier) that is unique for every device. This UUID allows Reporter data to be correlated with a specific device. In order for the correlation to work, the mobile app must display the UUID somewhere in its menu system (for example on the About or Help tabs).

    The app can retrieve the UUID from the SDK via the code sample below. The getDeviceUUID method is documented in the iOS SVM header file.

    
StadiumVisionMobile *svm = [StadiumVisionMobile sharedInstance];
NSString *deviceUUID = [svm getDeviceUUID];
NSLog(@"Device UUID is %@", deviceUUID);
Note The Cisco StadiumVision Mobile Device UUID should not be confused with the Unique Device Identifier (UDID) that is displayed in iTunes.

Google Android

Consider the following best practices when developing and delivering an app for Google Android:

Delivering Channel Content

  • Internet Group Management Protocol (IGMP) is a prerequisite for Cisco StadiumVision Mobile multicast to function correctly. Most, but not all, Android devices support IGMP. A user will see an empty channel list in the SVM app if they are using a device that does not support IGMP unless another active SVM client is associated to the same Access Point (AP). As a result, the user would experience sporadic channel support without knowing why. We recommend that all SVM-enabled Android apps perform the IGMP capability check as detailed in the example below. If the IGMP capability check returns false, then the app should warn the user when the user attempts to access any part of the app that relies on the SVM SDK.

    
boolean isCapable = false;
File f = new File("/proc/net/igmp");
if(f.exists()) {
isCapable = true;
}

Apple iOS, Google Android, and Windows Phone

Consider the following best practices when developing and delivering an app for Apple iOS, Google Android, and Windows Phone:

Delivering Channel Content

  • Start the SDK immediately when the app is launched or when the app detects that it is in venue. Do not wait until the user navigates to the SVM features in the UI. This ensures the best possible user experience so that content is then available to present to the user immediately. This is particularly important when using data and file channels because it can take several minutes for a content rotation to complete.

  • When a user selects a channel on their mobile device, there could be a 5-10 second delay before the app starts receiving multicast video if the client has to wait for the IGMP/PIM to set up the multicast tree. The same delay could occur when a device resumes from background or sleep mode. Instead of displaying a black screen, communicate to the user that their request is being processed by showing a transition graphic (for example a spinning wheel image) or text that asks them to please wait while the channel is located.

  • A channel will disappear from the lineup if it is stopped on the Streamer or if the Streamer detects a loss of input signal. The app should remove the channel immediately, however if a user is already watching the channel when it disappears, terminate the video rendering and return the user to the channel guide where they can select a new channel.

  • If the Cisco StadiumVision Mobile administrator starts the Streamer before the video control room has switched content to the encoder inputs, the user will receive an empty channel listing. To avoid a poor user experience, display a message indicating that there aren’t any live channels currently available.

Using the Latest Version of the app

  • Prevent or warn a user if they are attempting to access SVM services with an older or incompatible version of the app. Set the app to perform a self-check to see if a newer app version is available. If a new version is detected, the app should:

    • Block or warn the user that their app is out-of-date or may not perform as expected
    • Encourage the user to upgrade
Connecting to Wi-Fi

  • If the client looses complete Wi-Fi connectivity, the Operating System sends the app a notification. The app should notify the user that the Wi-Fi service is not available and remind them of the Wi-Fi network (SSID) to connect to.

  • If a Streamer service announcement has not been received for 30 seconds, the SDK will notify the user that the Cisco StadiumVision Mobile service is down. This could happen because the user exited the venue and is out of range, if their device roamed to a non SVM SSID, or if they entered an area in the venue without Wi-Fi. When this occurs, notify the user that the SVM service is not available and remind them of the name of the Wi-Fi network (SSID) that they must be connected to in order to receive the SVM service.

  • The SDK continuously monitors signal quality as a user moves throughout a venue. As a result, the SDK sends the app a ‘service down’ or ‘service up’ notification. These notifications can be used by the app for conditional playback based on network conditions. It is recommended that conditional playback is implemented as a passive informational service (as it should never display prompts that require an active response from the user). Refer the App Guideline table below as to how the app should respond depending on the state of the app when the notification is received.

App Guidelines for Responding to Notifications
app State Event or Notification Recommended app Response
The app is rendering a video. Service down notification, due to poor quality. Overlay the active video plane with a transparent graphic that contains the text such as, "Video quality degraded due to poor reception". The app continues the video session without interruption regardless of the poor quality and renders whatever video it receives underneath the text overlay.
The app previously received a service down notification with the poor quality reason code. It is currently rendering degraded video with the "Video quality degraded due to poor reception" overlay. Service down notification, due to poor quality. Remove the overlay and resume normal video rendering. Do not restart the video session.
The app is currently not rendering video. Service down notification, due to poor quality. Delete all channels from the channel list page and replace them with a message such as "Live video is currently unavailable due to poor reception".
The app is currently not rendering video. The app had previously received a service down notification with the poor quality reason code and is currently displaying the message "Live video unavailable due to poor reception" in the channel guide. Service up notification, due to quality rebounding. Remove the "Live video unavailable due to poor reception" message and populate the channel page with the current list of channels available.
The app previously received a service down notification with the poor quality reason code and is currently rendering video with the "Video quality degraded due to poor reception" overlay. The user now stops the video and returns to the channel page. Upon returning to the channel page, the user sees the message "Live video unavailable due to poor reception" instead of a list of channels.