iOS JShare 集成文档

使用提示

本文是 JSHARE iOS SDK 的标准集成指南文档。 匹配的 SDK 版本为:V1.9.0及以后版本。

  • 如果你想要快速测试、请参考本文在几分钟内跑通 Demo。
  • 极光文档官网上有相关的所有指南、API、教程等全部的文档。包括本文档的更新版本,都会及时地发布到该网站上。

产品功能说明

JSHARE SDK 可以让你的应用支持多平台分享,无需耗费时间了解、集成每个社会化分享平台的 SDK,可以有效的降低包体积。

主要场景:

  • 将分享内容分享到 QQ、微信、新浪微博、Facebook、Twitter、趣聊等主要的社交平台。
  • 获取QQ、微信、新浪微博、Facebook、Twitter等主要平台的个人信息,用于第三方登录。

资源文件

  • Libs 文件夹:包含头文件 JSHAREService.h,静态库文件 jshare-ios-x.x.x.a,jcore-ios-x.x.x.a
  • Libs-noidfa 文件夹:包含静态库文件jcore-noidfa-ios-x.x.x.a。
  • JiguangDemo 文件夹:示例

iOS SDK 支持版本

目前 JShare SDK 只支持 iOS8.0 及以上 iOS 版本。

DEMO使用

进入到JiguangDemo目录下,执行pod instal命令安装sdk,打开JiguangDemo.xcworkspace运行即可。

    JiguangDemo为多个SDK拼接组装而成的Demo,使用cocoapods进行管理,如需手动集成请参考[手动导入]部分。

JSHARE SDK 集成步骤

IDFA

从 JCore v2.1.4 开始,极光提供 idfa 和 noidfa 两个版本,请注意选择版本集成。 idfa 版本是标准版,默认自动采集 IDFA 数据, noidfa 版本不自动采集。极光建议开发者使用 idfa 版本。当然,如果开发者不想使⽤ IDFA 或者担忧采集 IDFA 而未集成任何广告服务遭到 Apple 拒绝,请使用 noidfa 版本。

注意事项

App在提交苹果审核时,对“此App是否使用广告标识符(IDFA)?”,需要选择“是”,并且需要根据App使用广告情况,勾选以下选项:

  • 在App内投放广告 -- 确认是的话需要勾选
  • 标明此App安装来自先前投放的特定广告 -- 确认是的话需要勾选
  • 标明此App中发生的操作来自先前投放的广告 -- 确认是的话需要勾选

添加SDK到工程中

选择1:Cocoapods导入

如果使用标准版本(默认采集IDFA)
  • 通过Cocoapods下载地址:
pod 'JShare'    //JCore自动集成最新版本的idfa包

注:如果无法导入最新版本,请执行 pod repo update master 这个命令来升级本机的 pod 库,然后重新 pod 'JShare'

  • 如果需要安装指定版本则使用以下方式(以1.8.1版本为例):
pod 'JCore', '2.1.4'  // 可选项,也可由pod 'JShare'自动获取最新版本
pod 'JShare', '1.8.1'
如果使用无IDFA版本
  • 如果使用 JCore 2.1.4 及以上版本,JCore使用方式如下(以 JShare 1.8.1 版本为例,需严格遵循代码顺序)
  pod 'JCore', '2.1.4-noidfa' // 必选项
  pod 'JShare', '1.8.1' // 必选项
  • 如果使用 JCore 2.1.4 以下版本,使用方式如下(以 JShare 1.8.1 版本为例,需严格遵循代码顺序):
  pod 'JCore', '2.1.2'  // 必选项
  pod 'JShare', '1.8.1'  // 必选项

选择2:手动集成

  • 解压压缩包,将 Libs 下的所有文件引用到工程中(或者只引用JSHAREService.h和jshare-ios-x.x.x.a),即可开始使用 SDK。
  • 注意选择使用标准版jcore-ios-xxx.a,还是noidfa版本jcore-noidfa-ios-xxx.a
  • 增加相关的 framework 依赖:

  • UIKit

  • SystemConfiguration
  • CoreTelephony
  • CoreGraphics
  • Security
  • CoreLocation
  • CoreFoundation
  • CFNetwork
  • libz.tbd
  • libresolv.tbd

  • 在 AppDelegate.m 引用头文件的位置

// 引入 JSHARE 功能所需头文件
#import "JSHAREService.h"
// 如果需要使用 idfa 功能所需要引入的头文件(可选)
#import <AdSupport/AdSupport.h>

SDK 主要接口说明

JSHARELaunchConfig 类:JSHARE SDK 启动配置模型。

JSHAREService 类,包含分享 SDK 的所有接口。

method - setupWithConfig

接口定义:

+(void)setupWithConfig:(JSHARELaunchConfig *)config

接口说明:

初始化接口。建议在 application:didFinishLaunchingWithOptions: 中调用。

参数说明:

  • config:JSHARELaunchConfig 类的实例。

调用示例:

    JSHARELaunchConfig *config = [[JSHARELaunchConfig alloc] init];
    config.appKey = @"AppKey copied from JiGuang Portal application";
    config.SinaWeiboAppKey = @"374535501";
    config.SinaWeiboAppSecret = @"baccd12c166f1df96736b51ffbf600a2";
    config.SinaRedirectUri = @"https://www.jiguang.cn";
    config.QQAppId = @"1105864531";
    config.QQAppKey = @"glFYjkHQGSOCJHMC";
    config.WeChatAppId = @"wxa2ea563906227379";
    config.WeChatAppSecret = @"bb63c0a06bf0ee7f633a5bc44304d110";
    config.FacebookAppID = @"1847959632183996";
    config.FacebookDisplayName = @"JShareDemo";
    config.TwitterConsumerKey = @"4hCeIip1cpTk9oPYeCbYKhVWi";
    config.TwitterConsumerSecret = @"DuIontT8KPSmO2Y1oAvby7tpbWHJimuakpbiAUHEKncbffekmC";
    config.JChatProAuth = @"a7e2ce002d1a071a6ca9f37d";
    config.universalLink = @"https://sv42fn.jmlk.co/ae68e02b59822c4ea458b74d/";
    [JSHAREService setupWithConfig:config];
    [JSHAREService setDebug:YES];

method - share

接口定义:

+(void)share:(JSHAREMessage *)message handler:(JSHAREStateHandler)handler

参数说明:

  • message:JSHAREMessage 类的实例
  • handler:JSHAREStateHandler 分享后的回调

调用示例:

JSHAREMessage *message = [JSHAREMessage message];
    message.text = @"JShare SDK 支持主流社交平台、帮助开发者轻松实现社会化功能!";
    message.platform = JSHAREPlatformQQ;
    message.mediaType = JSHAREText;
    [JSHAREService share:message handler:^(JSHAREState state, NSError *error) {
          NSLog(@"分享回调");
        }
    }];

method - share 仅支持JChatPro

接口定义:

  • (void)share:(JSHAREMessage *)message completionHandler:(JSHARECompletionHandler)handler ;

参数说明:

  • message:JSHAREMessage 类的实例
  • handler:JSHARECompletionHandler 分享后的回调

调用示例:

- (IBAction)shareGraphic:(id)sender {
    JSHAREMessage *message = [JSHAREMessage message];
    message.mediaType = JSHAREGraphic;
    message.url = @"http://tech.qq.com/zt2012/tmtdecode/252.htm";
    message.text = @"欢迎使用极光社会化组件 JShare,SDK 包体积小,集成简单,支持主流社交平台、帮助开发者轻松实现社会化功能";
    message.title = @"极光社会化组件";
    message.platform = JSHAREPlatformJChatPro;
    message.thumbUrl = @"http://img2.imgtn.bdimg.com/it/u=3721213387,3527941751&fm=27&gp=0.jpg";
    message.extInfo = @"extramessage";
    message.callbackUrl = @"https://www.jiguang.cn/";
    message.pkgName = @"android_pkg";
    message.className = @"android_class_name";
    message.appName = @"我是MT";
    message.fromScheme = @"jchatproa7e2ce002d1a071a6ca9f37d";

    [JSHAREService share:message completionHandler:^(JSHAREState state, NSError *error, id responseObject) {
        NSLog(@"responseObject :%@", responseObject);
        if (!error) {
            NSLog(@"分享图文成功");
        }else{
            NSLog(@"分享图文失败, error : %@", error);
        }
    }];
}

method - handleOpenUrl

接口定义:

+(BOOL)handleOpenUrl:(NSURL *)url

接口说明:

分享的回调接口,必要!

iOS 9以下,在 Appdelegate 的 application:handleOpenURL: 中调用; iOS 9以上,在 Appdelegate 的 application: openURL: options 中调用; iOS 10以上,支持 微信 Universal link 方式分享的在application:continueUserActivity:restorationHandler:中调用; iOS 13以上,如果实现了 SceneDelegate,则在scene:openURLContexts:方法中也需要调用。

参数说明:

  • url:回调的 url。

调用示例:

//目前适用所有 iOS 系统
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url{
    [JSHAREService handleOpenUrl:url];
    return YES;
}

//仅支持 iOS9 以上系统,iOS8 及以下系统不会回调
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    [JSHAREService handleOpenUrl:url];
    return YES;
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void(^)(NSArray<id<UIUserActivityRestoring>> * __nullable restorableObjects))restorationHandler API_AVAILABLE(ios(8.0)) {
    [JSHAREService handleOpenUrl:userActivity.webpageURL];
    return YES;
}

//实现了SceneDelegate 的时候调用
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    for (UIOpenURLContext *context in URLContexts) {
        NSURL *url = context.URL;
        [JSHAREService handleOpenUrl:url];
    }
}

method - getSocialUserInfo

接口定义:

+(void)getSocialUserInfo:(JSHAREPlatform)platform handler:(JSHARESocialHandler)handler

接口说明:

通过调用获取用户信息接口,获取用户在第三方平台的用户 ID、头像等资料完成账号体系的构建。

参数说明:

  • platform : JSHAREPlatform 枚举类型。
  • handler : JSHARESocialHandler 获取用户信息的回调。

调用实例:

[JSHAREService getSocialUserInfo:platfrom handler:^(JSHARESocialUserInfo *userInfo, NSError *error) {
        NSString *alertMessage;
        NSString *title;
        if (error) {
            title = @"失败";
            alertMessage = @"无法获取到用户信息";
        }else{
            title = userInfo.name;
            alertMessage = [NSString stringWithFormat:@"昵称: %@\n 头像链接: %@\n 性别: %@\n",userInfo.name,userInfo.iconurl,userInfo.gender == 1? @"男" : @"女"];
        }
        UIAlertView *Alert = [[UIAlertView alloc] initWithTitle:title message:alertMessage delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
        dispatch_async(dispatch_get_main_queue(), ^{
            [Alert show];
        });


    }];

其他接口详见 JSHAREService.h 。

Xcode 中的设置

配置 ApplicationQueriesSchemes

在 iOS9/10 下就需要增加一个应用可跳转的白名单,即 LSApplicationQueriesSchemes,否则将在 SDK 判断是否跳转时用到的canOpenURL 时返回 NO,进而只进行 webview 分享/分享失败。

注意:JShare1.9.0版本支持微信Universal link分享,微信跳转白名单必须配置:weixinULAPI,否则低版本微信可能分享失败。

在项目中的 info.plist 中加入应用白名单:

  • 右键 info.plist
  • 选择 source code
  • 添加如下内容:
<key>LSApplicationQueriesSchemes</key>
<array>
    <!-- 微信 URL Scheme 白名单-->
    <string>wechat</string>
    <string>weixin</string>
    <string>weixinULAPI</string>

    <!-- 新浪微博 URL Scheme 白名单-->
    <string>sinaweibohd</string>
    <string>sinaweibo</string>
    <string>sinaweibosso</string>
    <string>weibosdk</string>
    <string>weibosdk2.5</string>

    <!-- QQ、Qzone URL Scheme 白名单-->
    <string>mqqapi</string>
    <string>mqq</string>
    <string>mqqOpensdkSSoLogin</string>
    <string>mqqconnect</string>
    <string>mqqopensdkdataline</string>
    <string>mqqopensdkgrouptribeshare</string>
    <string>mqqopensdkfriend</string>
    <string>mqqopensdkapi</string>
    <string>mqqopensdkapiV2</string>
    <string>mqqopensdkapiV3</string>
    <string>mqqopensdkapiV4</string>
    <string>mqzoneopensdk</string>
    <string>wtloginmqq</string>
    <string>wtloginmqq2</string>
    <string>mqqwpa</string>
    <string>mqzone</string>
    <string>mqzonev2</string>
    <string>mqzoneshare</string>
    <string>wtloginqzone</string>
    <string>mqzonewx</string>
    <string>mqzoneopensdkapiV2</string>
    <string>mqzoneopensdkapi19</string>
    <string>mqzoneopensdkapi</string>
    <string>mqqbrowser</string>
    <string>mttbrowser</string>

    <!-- Facebook URL Scheme 白名单-->
    <string>fbapi</string>
    <string>fb-messenger-api</string>
    <string>fbauth2</string>
    <string>fbshareextension</string>

    <!-- Twitter URL Scheme 白名单-->
    <string>twitter</string>
    <string>twitterauth</string>

    <!-- JChatPro URL Scheme 白名单-->
    <string>JChatPro</string>
</array>

添加 URL Types

各个平台的 URL Schemes 格式说明:

平台 格式 举例
微信 微信 appKey wxa2ea563906227379
QQ 需添加:“tencent” + 腾讯 QQ 互联应用 appID 如 appID 为:1105864531
URL Schemes 值为:tencent1105864531
新浪微博 “wb”+新浪 appKey 如 appKey 为:727232518
URL Schemes 值为: wb727232518
Facebook “fb”+FacebookAppID 如 appID 为:1847959632183996
URL Schemes 值为: fb1847959632183996
Twitter “twitterkit-”+TwitterConsumerKey 如 TwitterConsumerKey 为:4hCeIip1cpTk9oPYeCbYKhVWi
URL Schemes 值为: twitterkit-4hCeIip1cpTk9oPYeCbYKhVWi
JChatPro “ jchatpro”+appkey 如 appkey为:a7e2ce002d1a071a6ca9f37d
URL Schemes 值为: jchatproa7e2ce002d1a071a6ca9f37d

URL Types 设置

Xcode 工程目录中的 [TARGETS] -> [Info] 中设置:

HTTPS 设置

Apple 将从2017年开始执行 ATS(App Transport Security),所有进行审核的应用中网络请求全部支持 HTTPS,届时以下配置将会失效,请提前做好准备。

目前 JSHARE 支持不存在新浪微博客户端情况下的网页分享,但是由于新浪微博的 api 尚未针对 https 做优化所以需要针对新浪的做对应的 https 设置。在 JSHARE 中是默认关闭新浪微博的网页端分享的,如需使用这个功能则需要在 JSHARELaunchConfig 类的实例中将 isSupportWebSina 属性设置为 YES。

以iOS10 SDK 编译的工程会默认以 SSL 安全协议进行网络传输,即 HTTPS,如果依然使用 HTTP 协议请求网络会报系统异常并中断请求。目前可用如下这种方式保持用 HTTP 进行网络连接:

在 info.plist 中加入安全域名白名单(右键 info.plist 用 source code 打开)

<key>NSAppTransportSecurity</key>
<dict>
    <!-- 配置允许 http 的任意网络 End-->
   <key>NSExceptionDomains</key>
   <dict>
       <!-- 集成新浪微博对应的 HTTP 白名单-->
       <key>sina.com.cn</key>
       <dict>
           <key>NSIncludesSubdomains</key>
           <true/>
           <key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
           <true/>
           <key>NSThirdPartyExceptionRequiresForwardSecrecy</key>
           <false/>
       </dict>
       <key>sinaimg.cn</key>
       <dict>
           <key>NSIncludesSubdomains</key>
           <true/>
           <key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
           <true/>
           <key>NSThirdPartyExceptionRequiresForwardSecrecy</key>
           <false/>
       </dict>
       <key>sinajs.cn</key>
       <dict>
           <key>NSIncludesSubdomains</key>
           <true/>
           <key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
           <true/>
           <key>NSThirdPartyExceptionRequiresForwardSecrecy</key>
           <false/>
       </dict>
       <key>sina.cn</key>
       <dict>
           <!-- 适配 iOS10 -->
           <key>NSExceptionMinimumTLSVersion</key>
           <string>TLSv1.0</string>
           <key>NSIncludesSubdomains</key>
           <true/>
           <key>NSThirdPartyExceptionRequiresForwardSecrecy</key>
           <false/>
       </dict>
       <key>weibo.cn</key>
       <dict>
           <!-- 适配 iOS10 -->
           <key>NSExceptionMinimumTLSVersion</key>
           <string>TLSv1.0</string>
           <key>NSIncludesSubdomains</key>
           <true/>
           <key>NSThirdPartyExceptionRequiresForwardSecrecy</key>
           <false/>
       </dict>
       <key>weibo.com</key>
       <dict>
           <!-- 适配 iOS10 -->
           <key>NSExceptionMinimumTLSVersion</key>
           <string>TLSv1.0</string>
           <key>NSIncludesSubdomains</key>
           <true/>
           <key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
           <true/>
           <key>NSThirdPartyExceptionRequiresForwardSecrecy</key>
           <false/>
       </dict>
       <!-- 新浪微博-->
   </dict>
</dict>

JShare 目前只支持微信平台使用 universal link 分享.

1.根据 苹果文档 配置你应用的Universal Links。 如果不想自行创建 Universal link,可以到 极光魔链 平台创建。

2.在微信开放平台创建移动应用,并配置好Universal link,注意sdk配置的 Universal link需要和微信开发平台配置的 Universal link一致。

3.在Xcode工程中选择相应的target,点击Signing & Capablities,添加Associated Domains,在里面添加 Universal link 的域名(比如:applinks:sv42fn.jmlk.co) 以及微信的域名:applinks:help.wechat.com

4.确认App的Universal Links配置成功 参考微信校验指引 验证 universal link 配置成功.

end


Copyright 2011-2020, jiguang.cn, All Rights Reserved.
粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

Documentation built with MkDocs.