BlazePlayerSourceDelegate iOS

BlazePlayerSourceDelegate is a protocol that defines the delegate methods for various player source interactions within the Blaze framework. It facilitates handling events related to data loading, player visibility, and actions within the player, customized for different player types and sources.

You can implement the following methods:

BlazePlayerSourceDelegate methods

onDataLoadStarted

/**
- playerType: The type of the player (`BlazePlayerType`).
- sourceId: The unique identifier of the player's source.
*/
typealias OnDataLoadStartedHandler = ((playerType: BlazePlayerType, sourceId: String?)) -> Void

/**
Called when the data loading process starts.
*/
var onDataLoadStarted: OnDataLoadStartedHandler? { get }

Called when the data loading process starts for a player of a specified type and source.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.

onDataLoadComplete

/**
- playerType: The type of the player (`BlazePlayerType`).
- sourceId: The unique identifier of the player's source.
- itemsCount: The number of items loaded.
- result: The result of the loading process, either success or failure.
*/
typealias OnDataLoadCompleteHandler = ((playerType: BlazePlayerType, sourceId: String?, itemsCount: Int, result: BlazeResult)) -> Void

/**
Called when the data loading process is complete.
*/
var onDataLoadComplete: OnDataLoadCompleteHandler? { get }

Called when the data loading process is complete for a player of a specified type and source.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.
• itemsCount: The number of items loaded.
• result: The result of the loading process, either success or failure.

onPlayerDidAppear

/**
- playerType: The type of the player (`BlazePlayerType`).
- sourceId: The unique identifier of the player's source.
*/
typealias OnPlayerDidAppearHandler = ((playerType: BlazePlayerType, sourceId: String?)) -> Void

/**
Called when a player becomes visible.
*/
var onPlayerDidAppear: OnPlayerDidAppearHandler? { get }

Called when a player of a specified type and source becomes visible.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.

onPlayerDidDismiss

/**
- playerType: The type of the player (`BlazePlayerType`).
- sourceId: The unique identifier of the player's source.
*/
typealias OnPlayerDidDismissHandler = ((playerType: BlazePlayerType, sourceId: String?)) -> Void

/**
Called when a player is dismissed.
*/
var onPlayerDidDismiss: OnPlayerDidDismissHandler? { get }

Called when a player of a specified type and source is dismissed.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.

onTriggerCTA

/**
- playerType: The type of the player (`BlazePlayerType`).
- sourceId: The unique identifier of the player's source.
- actionType: The type of the action triggered.
- actionParam: The parameter associated with the action.

- Returns: A boolean value indicating whether the CTA action was handled.
*/
typealias OnTriggerCTAHandler = ((playerType: BlazePlayerType, sourceId: String?, actionType: String, actionParam: String)) -> Bool

/**
Called when a Call to Action (CTA) is triggered for a player.
*/
var onTriggerCTA: OnTriggerCTAHandler? { get }

Called when a CTA (Call to Action) is triggered for a player of a specified type and source.

Use it to handle CTA actions like triggering deeplinks or opening webviews, if you wish to override the default handling.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.
• actionType: The type of the action triggered.
  • Available Types:
    • Web
    • Deeplink
• actionParam: The parameter associated with the action.
  • This is the action that is assigned to the CTA
    For example: "https://dev.wsc-sports.com/docs/getting-started"

Returns:

• A boolean value indicating whether the CTA action was handled.

onTriggerCustomActionButton

/**
     - playerType: The type of the player (`BlazePlayerType`).
     - sourceId: The unique identifier of the player's source.
     - customActionParams: The custom action button params.
*/
typealias OnTriggerCustomActionButtonHandler = ((playerType: BlazePlayerType, sourceId: String?, customActionParams: BlazePlayerCustomActionButtonParams)) -> Void

/**
Called when a custom action button  is triggered for a player.
*/
var onTriggerCustomActionButton: OnTriggerCustomActionButtonHandler? { get }

Called when a custom action button is triggered for a player of a specified type and source.

Use it to handle your custom action buttons.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.
• customActionParams: The custom action button params.

onTriggerPlayerBodyTextLink

/**
- playerType: The type of the player (`BlazePlayerType`).
- sourceId: The unique identifier of the player's source.
- actionParam: The parameter associated with the action.

- Returns: A `BlazeLinkActionHandleType` which action to perform.
*/
typealias OnTriggerPlayerBodyTextLinkHandler = ((playerType: BlazePlayerType, sourceId: String?, actionParam: String)) -> BlazeLinkActionHandleType

/**
Called when a body text link is triggered for a player.
*/
var onTriggerPlayerBodyTextLink: OnTriggerPlayerBodyTextLinkHandler? { get }

Called when a body text link is triggered for a player of a specified type and source.

Use it to handle links actions like triggering deeplinks or opening webviews, if you wish to override the default handling.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.
• actionParam: The parameter associated with the action.

Returns:

• A BlazeLinkActionHandleType which action to perform.

onPlayerEventTriggered

/**
- playerType: The type of the player (`BlazePlayerType`).
- sourceId: The unique identifier of the player's source.
- event: The event that was triggered (`BlazePlayerEvent`).
*/
typealias OnPlayerEventTriggeredHandler = ((playerType: BlazePlayerType, sourceId: String?, event: BlazePlayerEvent)) -> Void

/**
Called when an event is triggered for a player.
*/
var onPlayerEventTriggered: OnPlayerEventTriggeredHandler? { get }

Called when an event is triggered for a player of a specified type and source.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.
• event: The event that was triggered (BlazePlayerEvent).

onShareClicked

/**
 Called when the share button is clicked. Allows overriding the default SDK-generated share link with a custom one.
 - playerType: The type of the player (`BlazePlayerType`).
 - sourceId: The unique identifier of the player's source.
 - shareParams: The share parameters containing content ID, type, title, description, and the SDK-generated link.
 - Returns: A custom share link to use instead of the SDK-generated one, or `nil` to fall back to the default SDK share link.
 */
typealias OnShareClickedHandler = ((playerType: BlazePlayerType, sourceId: String?, shareParams: BlazeShareParams)) -> String?

/**
 Called when the share button is clicked. Return a custom share link or `nil` to use the SDK-generated link.
 */
var onShareClicked: OnShareClickedHandler? { get }

Called when the share button is clicked in a player of a specified type and source. This delegate allows the hosting app to override the default SDK-generated share link with a custom one.

By default (when not implemented or returning nil), the SDK uses its internal link generator — same as the existing behavior.

When the hosting app returns a custom link, the SDK uses that link for the share sheet instead of the default one.

Note: When providing a custom share link, the hosting app is fully responsible for handling and resolving that link when a user opens it. This includes parsing the link, extracting the content ID and type, and playing the appropriate content (e.g. via playStory, playMoment, playVideo). The SDK will not process custom share links — it only uses the returned link for the share sheet.

Parameters:

• playerType: The type of the player (BlazePlayerType).
• sourceId: The unique identifier of the player's source.
• shareParams: A BlazeShareParams object containing details about the content being shared:
  • id: The unique identifier of the content (story, moment, or video).
  • contentType: The type of the content (BlazeShareContentType).
    • Available Types:
      • .story(pageId: String) — a story page, with the specific page ID.
      • .moment — a moment (clip).
      • .video — a video.
  • title: The title of the content (optional).
  • description: The description of the content (optional).
  • sdkGeneratedLink: The default share link generated by the SDK. This is the link that would be used if the delegate is not implemented or returns nil.
  • extraInfo: Content-level extra info metadata for the shared item ([String: String]). For Stories this is the story's extra info; for Moments and Videos it is the item's own extra info. Empty when the content has no extra info. Always populated for content that has extra info — unlike analytics extra info, this is not gated by the analyticsAddExtraInfo remote flag.

Returns: A custom share link (String) to use for sharing, or nil to fall back to the default SDK share link.

Example:

var delegate = BlazePlayerWidgetDelegate()

delegate.onShareClicked = { params in
    let shareParams = params.shareParams
    
    // Build a custom share link using content details
    let customLink = "https://myapp.com/content/\(shareParams.contentType)/\(shareParams.id)"
    return customLink
    
    // Or return nil to use the SDK-generated link
    // return nil
}

onSearchClicked

/**
 Called when the search button is tapped in a player. Return a `BlazeSearchHandleType` to control
 the search behavior, or `nil` to use the default SDK behavior.
 */
typealias OnSearchClickedHandler = () -> BlazeSearchHandleType?

var onSearchClicked: OnSearchClickedHandler? { get }

Called when the search button is tapped in a player. Return a BlazeSearchHandleType to control the search behavior:

• .bySDK(params): The SDK opens the search screen with the provided BlazeSearchScreenParams.
• .byApp: The SDK does nothing; the client handles the action.
• nil (default): The SDK opens the search screen using the player's own data source as suggestions.

See BlazeSearchHandleType for details.

Enums

BlazeLinkActionHandleType

A type representing the available action for handling a link trigger.

BlazePlayerType

BlazePlayerType is an enumeration within the Blaze framework that categorizes different types of players. It is essential for distinguishing various player styles and functionalities, thereby enabling specific behaviors and features for each type.

Example of Usage

Ensure you avoid retain cycles regardless of the approach you choose to take. The delegates are strongly retained by their owner; hence, it's your responsibility to create a weak reference when needed.

Use the params tuple the SDK passes to the closure to access properties for that handler.

Initializer injection

Create a delegate instance and set it to the owner's property. The following example shows a Widget use case but applies to all delegate types the SDK provides.

 func createWidgetDelegate() -> BlazeWidgetDelegate {
        return BlazeWidgetDelegate(
            onDataLoadStarted: { [weak self] params in
                 print("onDataLoadStarted sourceId: \(params.sourceID)
            },
            onDataLoadComplete: { [weak self] params in
                 print("onDataLoadComplete)
            }, onPlayerDidDismiss: { [weak self] params in
                print("onPlayerDidDismiss)
            }, onTriggerCTA: { [weak self] params in
                print("onTriggerCTA action type: \(params.actionType)
            }
        )
    }

// Set the delegate property of the widget with the new instance
widgetView.widgetDelegate = createWidgetDelegate()

Property injection

The SDK provides a default implementation instance of the delegate, you don't have to create your own instance. Set the handler by directly accessing the owner's delegate property. The following example shows a Widget use case but applies to all delegate types the SDK provides.

 func setupWidgetDelegateHandlers() {
        widgetView.widgetDelegate.onDataLoadStarted = { [weak self] params in
            print("onDataLoadStarted source ID: \(params.sourceID)
        }
        
        widgetView.widgetDelegate.onDataLoadComplete = { [weak self] params in
            print("onDataLoadComplete)
        }
        
        widgetView.widgetDelegate.onPlayerDidDismiss = { [weak self] params in
            print("onPlayerDidDismiss)
        }
        
        
        widgetView.widgetDelegate.onTriggerCTA = { [weak self] params in
            print("onTriggerCTA action type: \(params.actionType)
        }
        
    }

The SDK provides a default implementation instance of the delegate, you don't have to create your own instance. Set the handler by directly accessing the owner's delegate property. The following example shows a Widget use case but applies to all delegate types the SDK provides.

 func setupWidgetDelegateHandlers() {
        widgetView.widgetDelegate.onDataLoadStarted = { [weak self] params in
            print("onDataLoadStarted source ID: \(params.sourceID)
        }
        
        widgetView.widgetDelegate.onDataLoadComplete = { [weak self] params in
            print("onDataLoadComplete)
        }
        
        widgetView.widgetDelegate.onPlayerDidDismiss = { [weak self] params in
            print("onPlayerDidDismiss)
        }
        
        
        widgetView.widgetDelegate.onTriggerCTA = { [weak self] params in
            print("onTriggerCTA action type: \(params.actionType)
        }
        
    }