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:
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:
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:
// 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:
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.
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:
@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:
/// 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:
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 |