Customize the share capacity

The mini program can be shared with others via the share capacity provided by the IAPMiniProgram SDK. Others who receive the share link via Facebook, Twitter, or other apps can open the shared mini program.

This topic guides you through how to customize the share capacity with the SDK in the following aspects:

  • Customize the share channels that your app supports such as Facebook, Twitter, WhatsApp, etc.
  • Customize the share panel.

Enable the share capacity

Ensure that the share capacity is enabled before implementing the customization.

Default user experience

After the share capacity is enabled, you can find the share menu in the menu panel. If you click the share menu, the share panel is displayed.

The following table shows the entry to the share panel and the default share panel:

image.png

image.png

Procedures to enable the share capacity

To enable the share capacity, complete the following steps:

Step 1: Implement ShareDelegate and makeLink(queryItems:)

Implement theShareDelegate protocol and the makeLink(queryItems:)function. Return the link that needs to be shared in themakeLink(queryItems:) function. Refer to the following sample for the implementation:

copy
class DemoShareDelegate: NSObject, ShareDelegate {
    func makeLink(queryItems: [URLQueryItem]) -> String {
        return "https://demo?" + queryItems
            .filter { $0.value != nil }
            .map { "\($0.name)=\($0.value!)" }
            .joined(separator: "&")
    }
}

For more information about the function, see makeLink(queryItems:).

Step 2: Configure ShareDelegate

Configure shareDelegate to IAPMiniProgram SDK with the following sample code:

copy
//  let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.shareDelegate = DemoShareDelegate();

Customize the share channels

After the share capacity is enabled, you have three share channels by default, which are listed as follows:

  • MessagesShareItem: Share message to SMS.
  • CopyUrlShareItem: Share message to the clipboard.
  • MoreShareItem: Share message to the system share panel.

If you want to share messages to other channels, you can make it by implementing the items(for:) function. Refer to the following sample for the implementation:

copy
class DemoShareDelegate: NSObject, ShareDelegate {

    func makeLink(queryItems: [URLQueryItem]) -> String {
        return "https://demo?" + queryItems
            .filter { $0.value != nil }
            .map { "\($0.name)=\($0.value!)" }
            .joined(separator: "&")
    }
   
    func items(for appId: String) -> [ShareItem] {
        let channel = "Custom"
        let custom = ShareItem(channel: channel, icon: nil) { context, viewController, completion in
            // do your share actionshare
            completion(true, channel)
        }
        return [custom, .system, .copyLink, .messages]
    }
}

For more information about the function, see items(for:).

Customize the share panel

IAPMiniProgram SDK provides the default share panel. If you want to customize the share panel, complete theshowPanel(items:context:visibleViewController:completion:)function as the following sample code.

copy
class DemoNewShareDelegate: NSObject, ShareDelegate {
    var items: [ShareItem]?

    func makeLink(queryItems: [URLQueryItem]) -> String {
        return "https://demo?" + queryItems
            .filter { $0.value != nil }
            .map { "\($0.name)=\($0.value!)" }
            .joined(separator: "&")
    }
   
    func items(for appId: String) -> [ShareItem] {
        let channel = "Custom"
        let custom = ShareItem(channel: channel, icon: nil) { context, viewController, completion in
            // do your share actionshare
            completion(true, channel)
        }
        return [custom, .system, .copyLink, .messages]
    }

    func showPanel(items: [ShareItem], context: ShareContext, visibleViewController: UIViewController?, completion: @escaping Completion) {
        self.items = items

        let alertController = UIAlertController(title: context.title, message: context.desc, preferredStyle: .actionSheet)
        items
            .map { item in
                UIAlertAction(title: item.channel, style: .default) { [weak alertController] action in
                    // do your share action
                    guard let alertController else { return }
                    alertController.dismiss(animated: true) {
                        item.handler?(context, visibleViewController, completion)
                    }
                }
            }
            .forEach(alertController.addAction(_:))

        let cancelAction = UIAlertAction(title: "Cancel", style: .cancel)
        alertController.addAction(cancelAction)
        visibleViewController?.present(alertController, animated: true)
    }
}

For more information about the function, see showPanel(items:context:visibleViewController:completion:).

Note:

  • After you customize the share channels, whether the default share channels are displayed depends on what you return in the items(for:) function. If you return default share channels, they are accordingly displayed on the share panel. Otherwise, only the customized share channels are displayed.
  • The lifecycle of the items parameter needs to be managed by yourself after the showPanel(items:context:visibleViewController:completion:)function is implemented.

Interface

Refer to the following sample code for the functions that need to be implemented to customize the share capacity:

copy
@objc
public protocol ShareDelegate: NSObjectProtocol {
    typealias Completion = (_ result: Bool, _ channel: String?) -> Void

    /// Generates a URL string for sharing with additional query items included in the URL.
    /// - Parameters:
    ///    - queryItems: An array of `URLQueryItem` to add to the URL.
    /// - Returns: The URL string
    func makeLink(queryItems: [URLQueryItem]) -> String

    /// Retrieves an array of `ShareItem` objects for a given mini program ID.
    /// - Parameter appId: The ID of the mini program for which to retrieve sharing items.
    /// - Returns: An array of `ShareItem` objects.
    @objc optional
    func items(for appId: String) -> [ShareItem]

    /// Presents a sharing panel to the user, allowing them to share the given items in the given context.
    /// - Parameters:
    ///    - items: An array of `ShareItem` objects to display in the sharing panel.
    ///    - context: A `ShareContext` object that defines the context in which the sharing panel is being displayed.
    ///    - visibleViewController: The view controller from which to present the sharing panel. If none is specified, the topmost view controller will be used.
    ///    - completion: A completion handler that is called when sharing is complete or canceled.
    ///         - result: A boolean value indicating whether the sharing operation was successful.
    ///         - channel: An optional string value indicating the channel through which the item was shared.
    @objc optional
    func showPanel(items: [ShareItem], context: ShareContext, visibleViewController: UIViewController?, completion: @escaping Completion)
}

makeLink(queryItems:)

The makeLink(queryItems:) function is used by the SDK to generate a URL string for sharing with additional query items included in the URL.

Request Parameter

Name

Type

Description

Required

queryItems

[URLQueryItem]

An array of URLQueryItem to add to the URL.

M

Response parameter

Name

Type

Description

Required

N/A

String

The URL string.

M

items(for:)

The items(for:) function is used by the SDK to retrieve an array of ShareItem objects for a given mini program ID.

Request parameter

Name

Type

Description

Required

appId

String

The ID of the mini program from which to retrieve sharing channels.

M

Response parameter

Name

Type

Description

Required

N/A

[ShareItem]

The customized list of sharing channels.

M

Refer to the following sample code for details about the ShareItem object:

copy
/// An object that represents a sharing channel.
@objcMembers
open class ShareItem: NSObject {
    
    public typealias Handler = (_ context: ShareContext, _ visibleViewController: UIViewController?, _ completion: @escaping ShareDelegate.Completion) -> Void
    
    /// The name of the sharing channel.
    public let channel: String
    
    /// The icon for the sharing channel.
    public let icon: UIImage?
    
    /// A boolean value indicating whether to use a short link for sharing.
    public let useShortLink: Bool
    
    /// A completion handler that is called when the sharing channel is selected.
    public var handler: Handler?
    
    /// Initializes a new `ShareItem` object.
    ///
    /// - Parameters:
    ///   - channel: The name of the sharing channel.
    ///   - icon: The icon for the sharing channel.
    ///   - useShortLink: A boolean value indicating whether to use a short link for sharing. Default is `false`.
    ///   - handler: A completion handler that is called when the sharing channel is selected. Default is `nil`.
    public init(channel: String, icon: UIImage?, useShortLink: Bool = false, handler: Handler? = nil) {
        self.channel = channel
        self.icon = icon
        self.useShortLink = useShortLink
        self.handler = handler
    }
}

Refer to the following sample for the functions contained in the ShareItem object:

copy
public extension ShareItem {

    public static var messages: ShareItem { get }

    public static var copyLink: ShareItem { get }

    public static var system: ShareItem { get }
}

showPanel(items:context:visibleViewController:completion:)

TheshowPanel(items:context:visibleViewController:completion:)function is used by the SDK to present a sharing panel to the user, which allows them to share the given items in the given context.

Parameters

Name

Type

Description

Required

items

ShareItem

An array of ShareItem objects that are displayed in the sharing panel.

M

context

ShareContext

A ShareContext object that defines the context in which the sharing panel is displayed.

M

visibleViewController

UIViewController?

The view controller from which to present the sharing panel. If it is not specified, the topmost view controller is used.

O

completion

Completion

A completion handler that is called when the sharing is completed or canceled.

M