# nexxPLAY for iOS You can find all necessary Binaries for Download and latest Changelogs always here: {% embed url="" %} ## 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” ### 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. The current version of IMA used in nexxPLAY is 3.17.0 and can be downloaded [here](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/download). 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 ```swift import UIKit import nexxPlay class ViewController: UIViewController { override func viewDidLoad() { super.viewDidLoad() let player = NexxPLAYView(frame: CGRect(x: 0, y: 0, width: 300, height: 300)) view.addSubview(player) player.setEnvironment(NexxPLAYEnvironment(domain: ":domainid")) player.startPlay(streamtype: ":streamtype", mediaID: ":mediaid", configuration: NexxPLAYConfiguration()) } } ``` {% hint style="info" %} As soon as the PlayerView is deallocated, the player will automatically stop. {% endhint %} ## 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 | | **campaign** | int | the ID of an existing Campaign of the calling Domain | | **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 Reference for this Player (a free String of "where is this Player located" for Reporting) | | **platformVariant** | String | the PlatformVariant for this Player (usefull Values will be given by 3Q) | | **platformVariantIndex** | Int | if platformVariant is not empty, this might further specify the current platform Variant. | | **appVersion** | String | the Version of the App, including the SDK | | **useSSL** | Bool | set to false if the Player should not use SSL (default is true) | | **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`**) | | **hideStatusbarOnFullscreen** | Bool | if set to true, the status bar is automatically hidden when the player is in fullscreen mode (default is **`false`**) | | **openPodcastURLsDirectly** | Bool | if set to true, podcast URLs will automatically be opened by the default browser application (default is **`false`**) | ## 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: {% content-ref url="/pages/-M9FfDOPhMEysfN-axhI" %} [SDK Override Options](/integration-enhancements/override-options.md) {% endcontent-ref %} {% hint style="info" %} Please notice, that some Options only make sense in the Web and are therefore not supported. {% endhint %} If you are looking for the TCF Consent String Management, this is documented here: {% content-ref url="/pages/-MGx77wpSdS\_W2GSojWL" %} [GDPR and TCF 2.0](/security-and-accessibility/gdpr-and-tcf-2.0.md) {% endcontent-ref %} ## Public Methods ### Preparing and Configuring the Player ```swift //Sets the environment object for the player. This method must be called before any start method is called setEnvironment(environment:NexxPLAYEnvironment) ``` ```swift //update a previously defined Environment Value //domain, language, sessionID and alwaysInFullscreen cannot be updated updateEnvironment(key:String, value:String) ``` ```swift //start the Player with the given Media startPlay(streamtype:String, mediaID:String, configuration:NexxPLAYConfiguration) ``` ```swift //start the Player with a given GlobalID startPlayWithGlobalID(globalID:String, configuration:NexxPLAYConfiguration) ``` ```swift //start the Player with a Remote Media Reference startPlayWithRemoteMedia(streamtype:String, reference:String, provider:String, configuration:NexxPLAYConfiguration) ``` ```swift //update a previously defined Configuration. //supported are currently only the ad*URL Configuration Settings (and webURLRepresentation). updateConfiguration(key:String, value:String) ``` ```swift //will clear all currently cached Data clearCache() ``` ### Playback Control ```swift //restart a paused Player play() ``` ```swift //pauses a playing Player pause() ``` ```swift //pauses/restarts a Player, depending on its current State toggle() ``` ```swift //mutes the Player mute() ``` ```swift //unmutes the Player unmute() ``` ```swift //seeks to the given Time, if the Media supports that seekTo(time:Float) ``` ```swift //seeks relatively by a certain amount of Seconds, if the Media supports that seekBy(seconds:Float) ``` ```swift //swap to the next Item in a Container Element next() ``` ```swift //swap to the previous Item in a Container Element previous() ``` ```swift //swap to a new Item in a Container Element swapToPosition(position:Int) ``` ```swift //swap to a completely new Media Item swapToMediaItem(mediaID:String, streamtype:String? = nil, startPosition:Int = 0, delay:Double = 0, reason:String? = nil, showReturnButton:Bool = false) ``` ```swift //swap to a completely new Media Item, referenced by a GlobalID swapToGlobalID(globalID:String, startPosition:Int = 0, delay:Double = 0, reason:String? = nil, showReturnButton:Bool = false) ``` ```swift //swap to a completely new Media Item, referenced by a Remote Reference swapToRemoteMedia(reference:String, streamtype:String? = nil, provider:String, delay:Double = 0, reason:String? = nil, showReturnButton:Bool = false) ``` ### Requesting Player Status and Details ```swift //returns Information about the currently played Media Item getCurrentMedia() -> [String:Any] ``` ```swift //returns Information about the Container Element of the currently played Media Item getCurrentMediaParent() -> [String:Any] ``` ```swift //returns Information about the current Playback State of the Player getCurrentPlaybackState() -> [String:Any] ``` ```swift //returns the text tracks of the current media item getTextTracks() -> [String:Any] ``` ```swift //returns all available Audio Tracks of the current Media getAudioTracks() -> [String:Any] ``` ```swift //returns the current playback time of the Player getCurrentTime() -> Float ``` ```swift //returns true, if the Player is currently playing isPlaying() -> Bool ``` ```swift //returns true, if the Player is currently playing an Ad isPlayingAd() -> Bool ``` ```swift //returns true, if the Player is currently muted isMuted() -> Bool ``` ```swift //returns true, if the Player is currently in PictureToPicture Mode isInPiP() -> Bool ``` ### LocalMedia and Offline Playback nexxPLAY for iOS also supports playback of previously downloaded media items and therefore offers some SDK methods to manage localMedia. ```swift //start a Download of a given Media Item (internal ID or Remote Reference) startDownloadLocalMedia(mediaID:String, streamtype:String, provider:String? = nil) ``` ```swift //returns a List of currently available localMedia Items listLocalMedia(streamtype:String) -> [[String:String]] ``` ```swift //returns true, if the referenced Media Item is already available locally hasDownloadOfLocalMedia(mediaID:String, streamtype:String, provider:String? = nil) -> Bool ``` ```swift //remove a previously downloaded Media Item removeLocalMedia(mediaID:String, streamtype:String, provider:String? = nil) ``` ```swift //remove all previously downloaded Media Items clearLocalMedia(streamtype:String? = nil) ``` ```swift //returns the currently used Storage by downloaded Media Items diskSpaceUsedForLocalMedia() -> Int64 ``` {% hint style="info" %} This Feature must be enabled within nexxOMNIA. Furthermore, various Settings to finetune the Details of the localMedia Behaviour can be setup there. Contact 3Q for more Information. {% endhint %} ## 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: ```swift NSNotificationCenter.defaultCenter().addObserver(self, selector: "notificationReceived:", name: nexxPlay.nexxPlayErrorNotification, object: playerView) ``` The appropriate function that is called when the notification is received: ```swift @objc func notificationReceived(notification:NSNotification) { println(notification.name) // prints “NexxPlayErrorNotification” if notification.name == nexxPlay.nexxPlayPlayPosNotification, let userInfo = notification.userInfo { // use the additional data in userInfo } } ``` 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: ```swift playerView.addObserverForAllNotifications(observer, selector:”notificationReceived:”) ``` Whenever a notification from playerView is received by the observer, the function**`notificationReceived`** is called. With **`notification.name`** you can determine which notification was received and act accordingly. There is also a convenience function to remove the observer for all notifications: ``` playerView.removeObserverForAllNotifications(observer) ``` You can find a List of all Player Notifications here: {% content-ref url="/pages/-M9Ff8FIIKv2tr-6mtmf" %} [Player Events](/integration-enhancements/player-events.md) {% endcontent-ref %} {% hint style="info" %} Please notice, that on iOS, the Events (Notifications) 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**" {% endhint %} ## 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 Picture-in-Picture 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. {% hint style="info" %} Picture-in-Picture AND AirPlay also requirs to be enabled in nexxOMNIA Player Settings and/or Configuration with Overrides. Additionally, it may not be available on all Devices, depending on Hardware Capabilities. {% endhint %} ### Widgets The iOS Platform also supports native Widgets by nexxPLAY. {% content-ref url="/pages/-MC-g-hgJ7a858hq4cS5" %} [Widgets for native Apps](/widgets/widgets-for-native-apps.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://play.docs.nexx.cloud/native-players/nexxplay-for-ios.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.