iOS Widget

For iOS, there are two possible Ways to bring a native Widget to iOS/iPadOS. The standard Way to add a Widget for the Homescreen is available sind iOS 14. Nevertheless, if also lower iOS Versions are supported, there is also a "Today Extension" which brings a simliar Experience to the Today Screen.

You will find the native SDK and the latest Changes here:

GitHub - 3qnexx/nexxPLAY-iOS: nexxPLAY SDK for iOSGitHub

Unlike android, there is no need for a different SDK, the nexxPLAY SDK includes Support for both Forms of Widgets.

Widget (iOS 14+)

Since iOS 14 Apple introduced Widgets that can be added to the springboard in different sizes. They behave just as the today extensions, presenting data from their corresponding app and deeplinking into the app once the user has selected an element or the widget itself. In order to add the NexxWidget to our application, please follow these steps:

1. In Xcode select your project and in the targets column, add a new target via the "+" on the bottom

2. Select the "Widget Extension" and give it an appropriate product name

3. In case you are asked to activate the target, please select "Activate"

4. Select your new target and add the nexxPLAY framework to "Frameworks and Libraries"

5. Switch to "Build Phases" and add the nexxPlay.bundle to "Copy Bundle Resources"

6. Remove all code above the @main in your widget code file so you only have the imports, the widget struct and its preview left.

7. Surround the complete code with a precompiler check for arm64 or simulators (see code example).

8. Configure the widget to your needs by modifying the WidgetConfiguration and WidgetData objects

9. Try and run the extension on device/simulator

#if arch(arm64) || arch(x86_64)
@main
struct MyWidget: Widget {
    private let kind: String = "MyWidget"
    
    var widgetData:NexxPLAYWidgetData {
        let config = NexxPLAYWidgetConfiguration(app: 0, language: "de", slideUpdateInterval: nil, feedUpdateInterval: nil,widgetPreviewImage: "", widgetPreviewTitle: "", widgetPreviewInfo: "")
        return NexxPLAYWidgetData(domain: "", launchURL: "", feedHash: "", feedSecret: "", userHash:"", config: config)
    }

    public var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: WidgetProvider(widgetData: widgetData)) { (entry) -> WidgetEntryView in
            WidgetEntryView(entry: entry)
        }
        .configurationDisplayName("My Widget")
        .description("my widget.")
        .supportedFamilies([.systemSmall,.systemMedium, .systemLarge])
    }
}

Today Extension (iOS 13)

1. In Xcode select your project and in the targets column, add a new target via the "+" on the bottom

2. Select the "Today Extension" and give it an appropriate product name

3. In case you are asked to activate the target, please select "Activate"

4. Select your new target and add the nexxPLAY framework to "Frameworks and Libraries"

5. Switch to "Build Phases" and add the nexxPlay.bundle to "Copy Bundle Resources"

6. In the project tree you should see a new folder with the name you gave the today extension in 2. Open the folder and open the TodayViewController

7. replace the code of the file with the following code:

8. Configure the extension to your needs by modifying the NexxPLAYWidgetConfiguration and NexxPLAYWidgetData objects

9. There should also be a "Maininterface.storyboard" that contains a UILabel by default. Please remove the label there.

import UIKit
import NotificationCenter
import nexxPlay

class TodayViewController: UIViewController, NCWidgetProviding {
        
    var nexxPLAYTodayView:NexxPLAYTodayView = NexxPLAYTodayView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        
        let config = NexxPLAYWidgetConfiguration(app: 0, language: "de", slideUpdateInterval: nil, feedUpdateInterval: nil,widgetPreviewImage: "", widgetPreviewTitle: "", widgetPreviewInfo: "")
        let widgetData = NexxPLAYWidgetData(domain: "", launchURL: "", feedHash: "", feedSecret: "", userHash:"", config: config)
        
        nexxPLAYTodayView.initializeView(withData: widgetData) { media in
            let urlString = "demoURL://..."
            if let url = URL(string: urlString) {
                self.extensionContext?.open(url, completionHandler: nil)
            }
        }
        nexxPLAYTodayView.add(toView: self.view)
    }
    
    func widgetPerformUpdate(completionHandler: (@escaping (NCUpdateResult) -> Void)) {
        nexxPLAYTodayView.widgetPerformUpdate() { (height) in
            if let height = height {
                self.extensionContext?.widgetLargestAvailableDisplayMode = .expanded
                self.preferredContentSize = CGSize(width: self.view.frame.size.width, height: height)
                completionHandler(.newData)
            } else {
                completionHandler(.failed)
            }
        }
    }
    
    func widgetActiveDisplayModeDidChange(_ activeDisplayMode: NCWidgetDisplayMode, withMaximumSize maxSize: CGSize) {
        self.preferredContentSize = nexxPLAYTodayView.widgetActiveDisplayModeDidChange(activeDisplayMode, withMaximumSize: maxSize)
    }
}

Extension data objects

There are two data objects that need to be provided for the extensions, so they can retreive and present the media data.

NexxWidgetData

Attribute	Type	Value
domain	String	the ID of the Domain (mandatory)
launchURL	String	the deeplink that is registered to open your application with the data of the selected media (mandatory)
feedHash	String	the Hash of the Feed, that the Widget will show
feedSecret	String	if the target Feed is secured by a Secret, ad this Value here
userHash	String	a valid User Reference Hash for personalized Results

The NexxPLAYWidgetConfiguration Object is the iOS Version of the Widget Override Object. You will find all Details here:

Widget Override Options

Additionally the NexxPLAYWidgetConfiguration object contains overrides for the preview:

Attribute	Type	Value
widgetPreviewImage	String	the name of an image from the apps assets that is presented in the preview
widgetPreviewTitle	String	the preview title
widgetPreviewInfo	String	the preview subtitle