nexxPLAY for iOS

nexxPLAY
Search…
Introduction
Javascript SDK
Integration Enhancements
nexxPLAY for iOS
nexxPLAY for iOS is a native Player, that is inteded to work in native iOS Apps
You can find all necessary Binaries for Download and latest Changelogs always here:
GitHub - 3qnexx/nexxPLAY-iOS
GitHub
General Integration
1.
In Xcode, select your project, select your target and open the tab “General”
2.
Drag the nexxPlay.framework file from the Finder to the “Embedded Binaries” section
3.
Please make sure that the framework is also included in “Linked Frameworks and Libraries”
4.
Change your tab to “Build Phases”
5.
Drag the nexxPlay.bundle from the Finder to the “Copy Bundle resources”
The next steps are only necessary if you use the SDK version 6.3.6 or earlier:
1.
Still in “Build Phases”, click on the “+“ icon and add a new run script phase
2.
Copy the code from the file “strip-framework.sh” into the run script phase. Please make sure that this run script phase is the last phase of the build process!
3.
IMPORTANT CHANGE IN XCODE 8, ONLY Objective-C: Change your tab to “Build Settings” and make sure that “Always Embed Swift Standard Libraries” is set to “YES” (the default value is “NO”)
IMA SDK - 3rd Party Library
nexxPLAY contains presenting video ads via the Google IMA SDK. If the Player will use this functionality, an additional SDK need to be added to the project.
Unfortunately the Google IMA SDK does not yet support the xcframework file format, so we created a xcframework version to use instead. It is available at github along with our SDK.
Please drag these frameworks into the "Embedded Binaries" section of your target (exactly as explained for the nexxPLAY framework) and make sure they also appear in the "Linked Frameworks and Libraries" section.
Adding a Player Instance
1
import UIKit
2
import nexxPlay
3
​
4
class ViewController: UIViewController {
5
​
6
    override func viewDidLoad() { 
7
        super.viewDidLoad()
8
        let player = NexxPLAYView(frame: CGRect(x: 0, y: 0, width: 300, height: 300)) 
9
        view.addSubview(player)
10
        player.setEnvironment(NexxPLAYEnvironment(domain: "1"))
11
        player.startPlay(streamtype: "video", mediaID: "12345", configuration: NexxPLAYConfiguration())
12
    }
13
}
Copied!
As soon as the PlayerView is deallocated, the player will automatically stop.
Player Environment
The NexxPLAYEnvironment object contains global settings for the player object. Except for the domain all the settings are optional and have a predefined value. The settings are:
Attribute
Type
Value
domain
String
the ID of the domain (mandatory)
sessionID
String
the ID of the current Session
language
2-Letter-Code
the Player Langage, will be computed by the System Language and Domain Settings if omitted
userHash
String
an Identifer of the currently loggedin User
externalUserReference
String
an Identifier of a User, that is not registered by nexxOMNIA
affiliatePartner
Int
the ID of an existing Affiliate Partner of the calling Domain
deliveryPartner
Int
the ID of an existing DeliveryPartner of the calling Domain
contextReference
String
the Context for this Player (for Reporting)
useSSL
Bool
set to false if the Player should not use SSL (default is false)
trackingOptOuted
Bool
if the App user explicitley opts out of Tracking and this Information is relevant for Ads, set this to true
consentString
String
in TCF/CMP Envrionments, the Player might need the User Consent String for Ad Calls
alwaysInFullscreen
Bool
initially and always show the Player in Fullscreen (default is false)
showCloseButtonOnFullscreen
Bool
set to false, if the Fullscreen should not show a "close" Button (default is true)
googleIMAReferenceViewController
UIViewController
the Google IMA SDK presents the advertisement modally on a UIViewController once the user taps the video ad. If the Google IMA SDK is used but no view controller is set, the advertisement will open in Safari (default is nil)
Player Configuration
Just like the Javascript Player, the Player can be configured by a Configuration Object. This Object will be used in one of the various play() Methods of the SDK.
All Options are identical to the general SDK Override Options, you will find here:
SDK Override Options
Please notice, that some Options only make sense in the Web and are therefore not supported. If you are looking for the TCF Consent String Management, this is documented here:
GDPR and TCF 2.0
Public Methods
Preparing and Configuring the Player
1
//Sets the environment object for the player. This method must be called before any start method is called
2
setEnvironment(environment:NexxPLAYEnvironment)
Copied!
1
//update a previously defined Environment Value
2
//domain, language, sessionID and alwaysInFullscreen cannot be updated
3
updateEnvironment(key:String, value:String)
Copied!
1
//start the Player with the given Media
2
startPlay(streamtype:String, mediaID:String, configuration:NexxPLAYConfiguration)
Copied!
1
//start the Player with a given GlobalID
2
startPlayWithGlobalID(globalID:String, configuration:NexxPLAYConfiguration)
Copied!
1
//start the Player with a Remote Media Reference
2
startPlayWithRemoteMedia(streamtype:String, reference:String, provider:String, configuration:NexxPLAYConfiguration)
Copied!
1
//update a previously defined Configuration. 
2
//supported are currently only the ad*URL Configuration Settings.
3
updateConfiguration(key:String, value:String) 
Copied!
1
//will clear all currently cached Data
2
clearCache()
Copied!
Playback Control
1
//restart a paused Player
2
play()
Copied!
1
//pauses a playing Player
2
pause()
Copied!
1
//pauses/restarts a Player, depending on its current State
2
toggle()
Copied!
1
//mutes the Player
2
mute()
Copied!
1
//unmutes the Player
2
unmute()
Copied!
1
//seeks to the given Time, if the Media supports that
2
seekTo(time:Float)
Copied!
1
//seeks relatively by a certain amount of Seconds, if the Media supports that
2
seekBy(seconds:Float)
Copied!
1
//swap to the next Item in a Container Element
2
next()
Copied!
1
//swap to the previous Item in a Container Element
2
previous()
Copied!
1
//swap to a new Item in a Container Element
2
swapToPosition(position:Int)
Copied!
1
//swap to a completely new Media Item
2
swapToMediaItem(mediaID:String, streamtype:String? = nil, startPosition:Int = 0, delay:Double = 0, reason:String? = nil, showReturnButton:Bool = false)
Copied!
1
//swap to a completely new Media Item, referenced by a GlobalID
2
swapToGlobalID(globalID:String, startPosition:Int = 0, delay:Double = 0, reason:String? = nil, showReturnButton:Bool = false)
Copied!
1
//swap to a completely new Media Item, referenced by a Remote Reference
2
swapToRemoteMedia(reference:String, provider:String, delay:Double = 0, reason:String? = nil, showReturnButton:Bool = false)
Copied!
Requesting Player Status and Details
1
//returns Information about the currently played Media Item
2
getMediaData() -> [String:Any]
Copied!
1
//returns the Captions of the current Media Item (or nil, if no Captions available)
2
getCaptionData(language:String? = nil) -> [String:String]
Copied!
1
//returns all available Caption Languages of the current Media
2
getCaptionLanguages() -> [String:String]
Copied!
1
//returns all available Audio Languages of the current Media
2
getAudioLanguages() -> [String:String]
Copied!
1
//returns the current playback time of the Player
2
getCurrentTime() -> Float
Copied!
1
//returns true, if the Player is currently playing
2
isPlaying() -> Bool
Copied!
1
//returns true, if the Player is currently playing an Ad
2
isPlayingAd() -> Bool
Copied!
1
//returns true, if the Player is currently muted
2
isMuted() -> Bool
Copied!
1
//returns true, if the Player is currently in PictureToPicture Mode
2
isInPiP() -> Bool
Copied!
LocalMedia and Offline Playback
nexxPLAY for iOS also supports Playback of previously downloaded Media Items and therefor offers some SDK Methods to manage localMedia.
1
//start a Download of a given Media Item (internal ID or Remote Reference)
2
startDownloadLocalMedia(mediaID:String, streamtype:String, provider:String? = nil)
Copied!
1
//returns a List of currently available localMedia Items
2
listLocalMedia(streamtype:String)
Copied!
1
//returns true, if the referenced Media Item is already available locally
2
hasDownloadOfLocalMedia(mediaID:String, streamtype:String, provider:String? = nil) -> Bool
Copied!
1
//remove a previously downloaded Media Item
2
removeLocalMedia(mediaID:String, streamtype:String, provider:String? = nil)
Copied!
1
//remove all previously downloaded Media Items
2
clearLocalMedia(streamtype:String? = nil)
Copied!
1
//returns the currently used Storage by downloaded Media Items
2
diskSpaceUsedForLocalMedia() -> Int64
Copied!
Player Notifications
Just like the JavaScript Player, the Player emits all Events to a Listener Function.
The notifications are sent by the NSNotificationCenter. To receive a notification you can use the following code snippet:
1
NSNotificationCenter.defaultCenter().addObserver(self, selector: "notificationReceived:", name: nexxPlay.nexxPlayErrorNotification, object: playerView)
Copied!
The appropriate function that is called when the notification is received:
1
@objc func notificationReceived(notification:NSNotification) {
2
    println(notification.name)        // prints “NexxPlayErrorNotification”
3
    if notification.name == nexxPlay.nexxPlayPlayPosNotification, let userInfo = notification.userInfo {
4
        // use the additional data in userInfo
5
    }
6
}
Copied!
If you have multiple players you can determine the player that sent the notification by checking notification.object
If you want to receive all notifications from the player, there is a convenience function:
1
playerView.addObserverForAllNotifications(observer, selector:”notificationReceived:”)
Copied!
Whenever a notification from playerView is received by the observer, the functionnotificationReceived is called. With notification.name you can determine which notification was received and act accordingly.
You can find a List of all Player Notifications here:
Player Events
Please notice, that on iOS, the Events (Notificationd) have a different Name, that is built by the following Rule: "nexxPlay" + EventName.camelCase() + "Notification". So for example, a "pause" Notification will become a "nexxPlayPauseNotification", and a "changeplaypos" Notification will become a "nexxPlayChangePlayPosNotification"
The following notifications include additional data in the userInfo dictionary:
error:
- reason: the reason for the error
- description: more details of the error
startplayback:
- isBumper: 1 in case the media is a bumper
- isMuted: 1 in case the media is started muted
- isPreview: 1 in case the media is a preview
- playReason: why or how the media is started (from exitDisplay, by a swap, by a hotspot etc.)
- isPresentation: always 0
- isStory: always 0
startplay:
- isBumper: 1 in case the media is a bumper
- isMuted: 1 in case the media is started muted
- isPreview: 1 in case the media is a preview
- playReason: why or how the media is started (from exitDisplay, by a swap, by a hotspot etc.)
- isPresentation: always 0
- isStory: always 0
play, pause, replay:
- byUserAction: 1 in case the action was triggered by user interaction
playpos:
- byUserAction: the index of the media in the list
exitfullscreen:
- shouldRemovePlayer: 1in case the player should be removed when exiting fullscreen
- reason: the reason for stopping fullscreen, such as "error"
adcalled, adstarted, adended, aderror, adclicked, adresumed:
- mode: "vast" or "ima"
- type: "pre", "mid", "banner", "post", "break", "bumper"
metadata:
- orientation: the orientation of the media
- hasAudio: 1 in case the media has audio
- aspectRatio: the aspect ratio of the current media
second, quarter:
- duration: the number of played seconds
- time: the position of the current media
- fullDuration: the length of the current media
- playbackSpeed: the playback speed
downloadstarted, downloadprogress, downloaderror, downloadsuccess:
- item: the media ID
- title: the title of the media
- progress: the progress of the download (only in downloadprogress event)
- error: the error description (only in the downloaderror event)
podcasturlselected:
- url: the url of the podcast
changemedia
- playmode: the new playmode
- param: the new media ID
changeplaypos:
- playpos: the new position
changemediaintent:
- direction: "next" or "prev"
playratechanged:
- speed: the new play rate
Additional Information
Fullscreen Behaviour
When the player switches to fullscreen, a subview (containing the video and all controls) of the PlayerView is added to the applications key window UIApplication.sharedApplication().keyWindow. Once the user switches back, the subview is added back to the PlayerView.
Orientation Behaviour
When the device is rotated, the video automatically rotates accordingly.
AirPlay and PictureInPicture Support
The player does support Airplay and PiP, if it is also supported by the device. 
Furthermore the Background Modes capability Audio, Airplay and Picture in Picture must be activated in your project settings in Xcode.
Widgets
The iOS Platform also supports native Widgets by nexxPLAY.
Widgets for native Apps
​