Customize the share capacity

2024-05-16 07:13

This document shows you how to customize the share capacity.

Users who open a mini program can share it with others by the share capacity provided by Griver AppContainer. And others who receive the share messages via Facebook, Twitter, or other apps will go to your app via the messages and open the shared mini program. In this way, more and more users can be reached with the share capacity.

As the share capacity is UI-related and you may want to customize it, Griver AppContainer provides you with a way to customize the share capacity. Totally speaking, there are four aspects that you need to customize if you want to integrate the share capacity.

The share panel when users start to share.
The share channels that your app supports such as Facebook, Twitter, or WhatsApp.
The share scheme that your app can recognize, for other users to go to your app from other apps.
The landing page of the share message which you need to register in the Mini Program Development Platform. The landing page is used to guide users to download or open your app.

Show your customized share panel

When users start to share the mini program from the share menu, Griver AppContainer receives the share message and then starts sharing. Griver AppContainer provides a delegate for you to render your customized share panel.

copy
@protocol GRVSharePanelDelegate <NSObject>

@required
/**
 Share info.
 
 You should implement showing share pannel , and complete  sharing logic for all channels.
 For your convenience, You can get the default sharing channels by GRVShareUtil's defaultShareItems method, which has implemented the sharing action.
 
 
 @param shareItemsList NSArray<GRVShareItem *>
 @param callback GRVShareCallbackBlock
 */
- (void)showSharePanelWithShareItemsList:(NSArray<GRVShareItem *> *)shareItemsList callback:(GRVShareCallbackBlock)callback;

@end

In this delegate, you will receive the detailed sharing information, the supported share channels, and the callback to return the share result.

You need to implement the extension and then configure the implementation to Griver AppContainer as follows.

copy
//  let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.uiProvider.sharePanelDelegate = DemoShareDelegate();

Share information

In the GRVShareItem, you can get the following information.

Property	Type	Nullable	Description
channelName	String	No	The name of the channel, such as `Facebook`, `Twitter`
icon	UIImage	Yes	The channel icon
isOutShareItem	BOOL	NO	The share for outers. If it is for sharing with outers, we will shorten the URL for you to share.
shareInfo	GRVShareParam	NO	The share information
doShareAction	GRVShareActionBlock	NO	The share action after clicking the share channel. If the share channel is an outer channel, call the `GRVShareUtil`'s method `getOutterShareParamWithOriginalParam` to get the `outShareParam`, and then call the `doShareAction(outShareParam, callback)`.

If the share channel is an outer channel, call the GRVShareUtil's method getOutterShareParamWithOriginalParam to get the outShareParam, and then call the doShareAction(outShareParam, callback). Here is a convenient method of the outer share param:

copy
@interface GRVShareUtil : NSObject

/**
 Get share param for outter share
 
 @param shareParam GRVShareParam
 @return GRVShareParam
 */
+(GRVShareParam *)getOutterShareParamWithOriginalParam:(GRVShareParam *)shareParam channelName:(NSString *)channelName;

@end

See the properties of GRVShareParam as follows:

Property	Type	Nullable	Description
currentViewController	Page	No	The current page of the mini program
activity	Activity	No	The current activity
title	String	No	The title of the share message
desc	String	Yes	The description of the share message
content	String	Yes	Content
URL	String	No	The scheme URL that you can use to open the shared mini program by `Griver.openUrl` and the scheme that your app can recognize
imageURL	String	No	The icon of the share message. It will be the icon URL of the mini program if the developer does not specify in the mini program.
bgImgURL	String	No	The preview image of the share message. It will be the snapshot of the current mini program page.
from	String	No	Where the user starts the sharing. It can be `menu`, `button`, or `code`.

You can use the above information to render a nice-looking share panel.

Share channels

See the default channels below to display in the share panel:

copy
@interface GRVShareUtil : NSObject

/**
 Default share channel lists.
 
 @return NSArray<GRVShareItem *>
 */
+(NSArray<GRVShareItem *> * _Nullable)defaultShareItems;

@end

And you can customize it through the following delegate:

copy
@protocol GRVShareListDelegate <NSObject>

@required
/**
 Get all share items.
 
 The share items should be showed on your share panel or the default share panel that SDK implemented.
 */
-(NSArray<GRVShareItem *> *)getShareItems;

@end

Configure it to Griver AppContainer as follows:

copy
// let extensionDelegate = GRVExtensionDelegate() 
extensionDelegate.uiProvider.shareListDelegate = DemoShareListDelegate();

Return share result

The GRVShareItem has a parameter doShareAction, which needs the callback to return the share result. See below the definition of the interface:

copy
typedef void (^GRVShareActionBlock)(GRVShareParam * _Nonnull shareInfo, GRVShareCallbackBlock callback);
typedef void (^GRVShareCallbackBlock)(GRVShareResult * _Nonnull shareResult);

When the sharing succeeds, call success with the shareResult. If failed, call fail with the shareResult. If users cancel the sharing, call cancel to tell Griver AppContainer that users cancel the sharing.

As mentioned above, each GRVShareItem handles the sharing separately, so you just need to call the share callback in the implementation of the doShareAction method of each sharing item.

Specify the share scheme

In the properties of the GRVShareParam, the URL is the share scheme. As Griver AppContainer does not know which scheme your app can recognize, you need to tell Griver AppContainer the scheme that your app supports. Or the shared message cannot lead users to go to your app.

Griver AppContainer provides the following extension for you to specify the share scheme.

copy
//let configuration = GRVConfiguration()
configuration.appScheme = "DemoScheme"

Register landing page in Mini Program Developer Platform

When sharing a mini program with a third-party app, take Facebook as an example, in order to navigate users who check the share message in the Facebook app back to your app, you need to share a URL to the Facebook app so that the Facebook app can browse the URL, which we call the landing page. Then users can browse the landing page. On the landing page, you can lead users to go back to your app with the scheme mentioned before.

In this way, before sharing to Facebook, we need to add the landing page with the scheme URL in the GRVShareParam. Our Mini Program Developer Platform has achieved this function. We will send the scheme URL to our Mini Program Developer Platform and then get the shortened URL. As the URL should be related to your app, you need to register the landing page URL to the Mini Program Platform. Then we can add the URL automatically.

The Griver AppContainer completes this process in the GRVShareUtil's method as follows:

copy
@interface GRVShareUtil : NSObject
/**
 Get share param for outter share
 
 @param shareParam GRVShareParam
 @return GRVShareParam
 */
+(GRVShareParam *)getOutterShareParamWithOriginalParam:(GRVShareParam *)shareParam channelName:(NSString *)channelName;

@end

To handle the scheme URL yourself, do not call the getOutterShareParamWithOriginalParam method before you click the share channel item.

With the above work, the share capacity is fully integrated, then users can share the mini program with others and let more users know your app.

Demo Show

How to use the GRVShareUtil class method getOutterShareParamWithOriginalParam:channelName:?

When you click one item with the original shareParam for outer sharing, you should get the outer parameter first, and then do the share action.

copy
//In Share View, you can get all share items from 'shareListDelegate',or from GRVShareUtil's mehod defaultShareItems. So when you click one item, you can manage the item with its share info.
- (void)clickShareItem:(GRVShareItem *)shareItem {
    if(shareItem.isOutterShareItem) {
        GRVShareParam *outShareParam = [GRVShareUtil getOutterShareParamWithOriginalParam:shareItem.shareInfo channelName:shareItem.channelName callback:self.callback];
        shareItem.doShareAction(outShareParam,self.callback);
    } else {
        shareItem.doShareAction(shareItem.shareInfo,self.callback);
    }
}

How to manage your share item list with the default share items?

copy
@interface DemoShareListDelegate : NSObject<GRVShareListDelegate>

@end

@implementation DemoShareListDelegate

- (NSArray<GRVShareItem *> *)getShareItems {
    // new share list
    NSMutableArray *shareList = [[NSMutableArray alloc] init];
    
    //default share list
    NSArray *defaultShareList = [GRVShareUtil defaultShareItems];
    if(defaultShareList){
        [shareList addObjectsFromArray:defaultShareList];
    }
    
    // facebook share item
    GRVShareItem *facebookShareItem = [self facebookShareItem];
    [shareList addObject:facebookShareItem];
}
    
    //facebook
- (GRVShareItem *)facebookShareItem {
    NSString *faceBookChannelName = @"Facebook";
    GRVShareItem *facebookShareItem = [[GRVShareItem alloc] initWithChannelName:faceBookChannelName icon:[UIImage imageNamed:@"grv_facebook"] isOutterShareItem:YES];
    
    facebookShareItem.doShareAction = ^(GRVShareParam * _Nonnull shareInfo, GRVShareCallbackBlock callback) {
        SLComposeViewController *fbSLComposerController = [SLComposeViewController composeViewControllerForServiceType:SLServiceTypeFacebook];
        if (!fbSLComposerController) {
            [self callback:callback shareResultType:GRVShareResultTypeFail channel:faceBookChannelName errorCode:nil errorMessage:nil];
            return;
        }
        [fbSLComposerController setInitialText:shareInfo.URL];
        fbSLComposerController.modalPresentationStyle = UIModalPresentationFullScreen;
        [fbSLComposerController setCompletionHandler:^(SLComposeViewControllerResult result) {
            switch (result) {
                case SLComposeViewControllerResultCancelled:
                    [self callback:callback shareResultType:GRVShareResultTypeCancel channel:faceBookChannelName errorCode:nil errorMessage:nil];
                    break;
                case SLComposeViewControllerResultDone:
                    [self callback:callback shareResultType:GRVShareResultTypeSuccess channel:faceBookChannelName errorCode:nil errorMessage:nil];
                    break;
                default:
                    break;
            }
        }];
        [shareInfo.currentViewController presentViewController:fbSLComposerController animated:YES completion:nil];
    };
}
@end