Share 集成指南

For the C++ version of cocos2d-x v3.x - (all other versions)

简介

SDKBOX Share 插件为开发者提供一种终极的解决方案实现所有社交平台的分享功能。

当前 Sdkbox Share 支持分享到 twitter 以及 facebook 。

在使用前，请确保您已经在下面两个平台创建了开发者帐号。

集成

在您确保正确安装了 SDKBOX installer 的情况下，运行下面的命令来集成 SDKBOX Share 插件。

$ sdkbox import share

如果您希望使用分享到 Facebook 功能，您必须安装 SDKBOX Facebook 插件。

$ sdkbox import facebook

Facebook 插件的安装集成还需要一些额外的集成步骤，请参考这篇文档。

重点注意事项

如果您升级到了 Xcode7, 则需要以下额外步骤来确保插件工作正常:

禁用应用程序安全传输策略

添加以下项到 plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

添加后的文件内容看起来就像这样：

禁止 Bitcode 支持

您必须禁止 Bitcode 的支持，否则将会编译失败。

游戏全屏配置

如果您的游戏不同时支持横竖屏，则必须在 Xcode 中选中 Requires full screen，否则将不会通过 Apple 的审核。

canOpenURL 白名单

取决于您使用哪些插件。需要在 info.plist 的 LSApplicationQueriesSchemes 下添加名单。

关于 Creator 工程

Creator 导出工程会修改工程的配置, 这可能会影响 SDKBox 对工程的配置修改. 所以可以有以下做法(任选其一):

保存导出工程中的修改, 对于 SDKBox 来说可能有这些文件(mk, gradle, gradle.properties, AppDelegate.cpp, ...), 导出后再恢复对应该文件
在每一次 Creator 导出工程后, 重新 import 插件.

推荐第一种, 但是第一种的麻烦点在于, 对于第一次(或很久没接触的人)可能会有露掉某个文件第二种, 很方便, 它的麻烦点在于, 如果你对工程有自己的修改, SDKBox 的重新 import 不能帮你恢复.

JSON 配置

SDKBOX Installer 将会自动在您的 sdkbox_config.json 中插入一份配置样例。请修改这份配置样例，使其能用于您自己的 app 。

这里有一个 Sdkbox Share 的配置示例如下：

    "android": {
        "Facebook": {
            "debug": false
        },
        "Share": {
            "platforms": {
                "Twitter": {
                    "params": {
                        "secret": "nlmUdPNcFGLWhyLu9cD794EDuDrVQnjd0YjTpB6sX8oHIQRrne",
                        "key": "EuovpLL0UhSGB7Jv5eKFJNMqO"
                    }
                },
                "Facebook": {}    //support facebook share
            }
        }
    },
    "ios": {
        "Facebook": {
            "debug": true
        },
        "Share": {
            "platforms": {
                "Twitter": {
                    "params": {
                        "secret": "haVcKarM96Sr4390XLQoHjyRUSyuHdkMX6letcc38h8TOWyiR9",
                        "key": "BUJTV6NEM7BAhhm82B12VbKGy"
                    }
                },
                "Facebook": {}    //support facebook share
            }
        }
    }

Twitter 配置

you need to replace <key>, <secret> item with your specific Twitter account. 您需要用您自己的 Twitter 开发者帐号信息替换配置文中所有的 <key>，<secret> 项。

Facebook 配置

您需要添加 Facebook 相关配置到配置文件中。

iOS 配置

Twitter 支持的 iOS 版本为 9.0+
在 AppController.mm 中做如下修改

#import <TwitterKit/TWTRKit.h>

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    return [[Twitter sharedInstance] application:app openURL:url options:options];
}

在 Info.plist 中增加如下内容

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>

    ...

    <key>CFBundleURLTypes</key>
    <array>

        ...

        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>twitterkit-(your-appkey)</string>
            </array>
        </dict>

        ...

    </array>

    <key>LSApplicationQueriesSchemes</key>
    <array>

        ...

        <string>twitter</string>
        <string>twitterauth</string>

        ...

    </array>

    ...

</dict>
</plist>

使用

在您的代码的合适的位置初始化这个插件，我们建议您在 AppDelegate:applicationDidFinishLaunching() 或者 AppController:didFinishLaunchingWithOptions() 中进行初始化。并确保您的代码中包含了正确的头文件。举例如下：

#include "PluginShare/PluginShare.h"
AppDelegate::applicationDidFinishLaunching()
{
     sdkbox::PluginShare::init();
}

分享内容

在初始化之后，您可以开始使用内容分享功能了：

sdkbox::SocialShareInfo info;
info.text = "#sdkbox(www.sdkbox.com) - the cure for sdk fatigue ";
info.title = "sdkbox";
info.image = "http://www.sdkbox.com/assets/images/logo.png";
info.link = "http://www.sdkbox.com";

//sdkbox::SocialPlatform::Platform_Select will show platforms list, let user select which platform want to share
//sdkbox::SocialPlatform::Platform_Twitter will share with twitter directly
//sdkbox::SocialPlatform::Platform_Facebook will share with facebook directly
info.platform = sdkbox::SocialPlatform::Platform_Select;
sdkbox::PluginShare::share(info);

系统分享

你也可以使用 ios/android 系统自带提供的分享功能:

sdkbox::SocialShareInfo info;
info.text = "#sdkbox(www.sdkbox.com) - the cure for sdk fatigue ";
info.title = "sdkbox";
//info.image = "path/to/image"
info.link = "http://www.sdkbox.com";
sdkbox::PluginShare::nativeShare(info);

// 使用系统分享，以下两个属性无效
//info.showDialog = false;
//info.platform = sdkbox::SocialPlatform::Platform_Select;

sdkbox::PluginShare::nativeShare(info);

注意:

IOS: 分享成功后，会收到分享成功事件，具体分享对应的操作会在 sdkbox::SocialShareResponse 的 error 属性中
Android: 能收到分享成功事件，但是这个不是真正意义的分享成功, 只是把分享的对话框显示出来了, 因为在 android 上, 无法收到分享成功的事件

捕获 Share 事件（可选）

该插件允许您捕获 Share 事件以帮助您根据返回的内容进行相应的操作。一个简单的例子如下：

允许您的类继承 sdkbox::ShareListener 类

#include "PluginShare/PluginShare.h"
class SListener : public sdkbox::ShareListener {
public:
    virtual void onShareState(const sdkbox::SocialShareResponse& response) {
        switch (response.state) {
            case sdkbox::SocialShareState::SocialShareStateNone: {
                CCLOG("SharePlugin::onShareState none");
                break;
            }
            case sdkbox::SocialShareState::SocialShareStateUnkonw: {
                CCLOG("SharePlugin::onShareState unkonw");
                break;
            }
            case sdkbox::SocialShareState::SocialShareStateBegin: {
                CCLOG("SharePlugin::onShareState begin");
                break;
            }
            case sdkbox::SocialShareState::SocialShareStateSuccess: {
                CCLOG("SharePlugin::onShareState success");
                break;
            }
            case sdkbox::SocialShareState::SocialShareStateFail: {
                CCLOG("SharePlugin::onShareState fail, error:%s", response.error.c_str());
                break;
            }
            case sdkbox::SocialShareState::SocialShareStateCancelled: {
                CCLOG("SharePlugin::onShareState cancelled");
                break;
            }
            case sdkbox::SocialShareStateSelectShow: {
                CCLOG("SharePlugin::onShareState show pancel %d", response.platform);
                break;
            }
            case sdkbox::SocialShareStateSelectCancelled: {
                CCLOG("SharePlugin::onShareState show pancel cancelled %d", response.platform);
                break;
            }
            case sdkbox::SocialShareStateSelected: {
                CCLOG("SharePlugin::onShareState show pancel selected %d", response.platform);
                break;
            }
            default: {
                CCLOG("SharePlugin::onShareState");
                break;
            }
        }
    }
};

创建一个 listener 处理回调：

sdkbox::PluginShare::setListener(this);

API Reference

Methods

static bool init ( ) ;

initialize the plugin instance.

static void setListener ( ShareListener * listener ) ;

Set listener to listen for share events

static ShareListener * getListener ( ) ;

Get the listener

static void removeListener ( ) ;

Remove the listener, and can't listen to events anymore

static void share ( const ShareInfo & info ) ;

Share content

Listeners

void onShareState ( const PluginShare::ShareResponse & response ) {

Notifies the delegate that share completion

手动集成

如果 SDKBOX 安装器 安装插件失败了，那么需要手动集成插件.如果安装器安装插件成功了,那么不需要，也没必要,按文档再手动集成一次.

下面列出的的步骤一般很少用到.如果你按下面的步骤完成了集成，请在完成集成后，再按步骤检查一次.

iOS 平台手动集成

拖拽下列 framework 从 Share 插件包的 plugins/ios 目录到您的 Xcode 工程中，在添加 frameworks 的时候，请勾选 Copy items if needed 。

sdkbox.framework

PluginShare.framework

TwitterCore.framework

TwitterKit.framework

TwitterKitResources.bundle -> TwitterKit.framework/TwitterKitResources.bundle

TwitterShareExtensionUIResources.bundle -> TwitterKit.framework/TwitterShareExtensionUIResources.bundle

如果您没有添加下面这些系统库，您有需要添加它们：

Accounts.framework

CoreText.framework

CoreMedia.framework

CoreData.framework

Social.framework

GameController.framework

SystemConfiguration.framework

MediaPlayer.framework

MessageUI.framework

CoreMotion.framework

SafariServices.framework

Android 手动集成

SDKBox 支持三种 Android 工程, command-line, eclipse 和 Android Studio.

command-line 和 eclipse 类型的项目, <project_root> 指代 proj.android .
Android Studio 类型的项目, <project_root> 指代 proj.android-studio .

拷贝文件

从插件安装包中的 plugin/android/libs 目录拷贝下列 jar 文件到您的工程的 proj.android/libs 目录。

sdkbox.jar

PluginShare.jar

converter-gson-2.1.0.jar

gson-2.7.jar

okhttp-3.4.2.jar

okio-1.9.0.jar

picasso-2.5.2.jar

retrofit-2.1.0.jar

twitter-text-1.14.3.jar

tweet-composer

twitter-core

如果你使用 cocos2d-x 源码，拷贝 jar 文件到：

Android command-line: cocos2d/cocos/platform/android/java/libs

Android Studio: cocos2d/cocos/platform/android/libcocos2dx/libs
如果你使用 cocos2d-js 或者 lua ，拷贝 jar 文件到:

Android command-line: frameworks/cocos2d-x/cocos/platform/android/java/libs

Android Studio: frameworks/cocos2d-x/cocos/platform/android/libcocos2dx/libs
如果你使用 cocos2d-x 预编译包，拷贝 jar 文件到：

Android command-line: proj.android/libs
如果您使用 android-stdio, 请编辑 proj.android-studio/app/build.gradle 文件，如下所示：

文件 proj.android-studio/app/build.gradle 中 dependencies tag 的内容：

    dependencies {

        ...

        implementation 'com.twitter.sdk.android:twitter-core:3.1.1'
        implementation 'com.twitter.sdk.android:tweet-composer:3.1.1'

        ...

    }

拷贝 jni 库

从 plugin/android/jni/ 拷贝并覆盖 <your_project_root>/jni/ 目录.

编辑 `AndroidManifest.xml`

在标签 application tag 上添加下列权限：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

在标签 application tag 上包含以下内容：

<activity
    android:name="com.twitter.sdk.android.core.identity.OAuthActivity"
    android:configChanges="orientation|screenSize"
    android:excludeFromRecents="true"
    android:exported="false" />

<service
    android:name="com.twitter.sdk.android.tweetcomposer.TweetUploadService"
    android:enabled="true"
    android:exported="false" />

编辑 `Android.mk`

编辑 proj.android/jni/Android.mk：

为 LOCAL_WHOLE_STATIC_LIBRARIES 添加额外的库：

LOCAL_WHOLE_STATIC_LIBRARIES += PluginShare
LOCAL_WHOLE_STATIC_LIBRARIES += sdkbox

在所有 import-module 语句之前添加一条 call 语句：

$(call import-add-path,$(LOCAL_PATH))

在最后添加额外的 import-module 语句：

$(call import-module, ./sdkbox)
$(call import-module, ./pluginshare)

这意味着您的语句顺序看起来像是这样：

$(call import-add-path,$(LOCAL_PATH))
$(call import-module, ./sdkbox)
$(call import-module, ./pluginshare)

Note: 如果您使用的是 cocos2d-x 预编译库，那么保证这些语句在已有的 $(call import-module,./prebuilt-mk) 语句之上非常重要。

编辑 `Application.mk` （只限 Cocos2d-x v3.0 到 v3.2 版本）

编辑 proj.android/jni/Application.mk 保证 APP_STL 的定义正确。如果 Application.mk 包含了 APP_STL := c++_static 语句，那么这条语句应该被改为：

APP_STL := gnustl_static

修改 `AppActivity.java`

插件版本 >= 2.4.0.3

找到 AppActivity.java 文件

find . -name "AppActivity.java"

把 extends Cocos2dxActivity 替换为 extends com.sdkbox.plugin.SDKBoxActivity

以下是 AppActivity.java 不同版本的引擎所在的目录：

cpp
  - proj.android/src/org/cocos2dx/cpp/AppActivity.java
  - proj.android-studio/app/src/org/cocos2dx/cpp/AppActivity.java
  - proj.android/app/src/org/cocos2dx/cpp/AppActivity.java ( from cocos2d-x 3.17)

lua
  - frameworks/runtime-src/proj.android/src/org/cocos2dx/lua/AppActivity.java
  - frameworks/runtime-src/proj.android-studio/app/src/org/cocos2dx/lua/AppActivity.java
  - frameworks/runtime-src/proj.android/app/src/org/cocos2dx/lua/AppActivity.java (from cocos2d-x 3.17)

js
  - frameworks/runtime-src/proj.android/src/org/cocos2dx/javascript/AppActivity.java
  - frameworks/runtime-src/proj.android/app/src/org/cocos2dx/javascript/AppActivity.java ( from cocos2d-x 3.17)

插件版本 < 2.4.0.3

如果您使用 cocos2d-x 源代码，假设您在 proj.android 目录下，那么您可以在如下位置找到 Cocos2dxActivity.java 文件：

../../cocos2d-x/cocos/platform/android/java/src/org/cocos2dx/ lib/Cocos2dxActivity.java
如果您使用 cocos2dx-x 预编译库，假设您在 proj.android 目录下，那么您可以在如下位置找到 Cocos2dxActivity.java 文件：

./src/org/cocos2dx/lib/Cocos2dxActivity.java

Note: 当你使用 cocos2d-x 源代码时，不同的版本中 Cocos2dxActivity.java 文件的位置也不同。一个确定该文件位置的方法是查看 proj.android/project.properties 。比如：

android.library.reference.1=../../cocos2d-x/cocos/platform/android/java

在这个例子中， Cocos2dxActivity.java 文件应该在如下位置：

../../cocos2d-x/cocos/platform/android/java/src/org/cocos2dx/lib/Cocos2dxActivity.java

修改 Cocos2dxActivity.java 文件，导入如下包：

import android.content.Intent;
import com.sdkbox.plugin.SDKBox;

然后，修改 Cocos2dxActivity 类的 onCreate(final Bundle savedInstanceState) 函数，添加一个调用语句 SDKBox.init(this); 。添加的位置非常重要，必须在调用 onLoadNativeLibraries(); 之后。如下：

onLoadNativeLibraries();
SDKBox.init(this);

最后, 我需要提供合适的 overrides 方法的代码。这里有一些约定如下。
- 如果这个被列出的方法没有在 SDKBox 中定义，那么__定义它__。
- 如果这个被列出的方法已经被定义在 SDKBox 中，那么请调用这个在 SDKBox 中的__同名方法__。

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
          if(!SDKBox.onActivityResult(requestCode, resultCode, data)) {
            super.onActivityResult(requestCode, resultCode, data);
          }
    }
    @Override
    protected void onStart() {
          super.onStart();
          SDKBox.onStart();
    }
    @Override
    protected void onStop() {
          super.onStop();
          SDKBox.onStop();
    }
    @Override
    protected void onResume() {
          super.onResume();
          SDKBox.onResume();
    }
    @Override
    protected void onPause() {
          super.onPause();
          SDKBox.onPause();
    }
    @Override
    public void onBackPressed() {
          if(!SDKBox.onBackPressed()) {
            super.onBackPressed();
          }
    }

使用 Proguard （release模式下可选）

编辑 project.properties 文件，指定一个 Proguard 配置文件。比如：

proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt

编辑这个配置文件，加入如下内容：

# share
-keep class com.share.** { *; }
-dontwarn com.share.**


# cocos2d-x
-keep public class org.cocos2dx.** { *; }
-dontwarn org.cocos2dx.**
-keep public class com.chukong.** { *; }
-dontwarn com.chukong.**

#sdkbox
-keep public class com.sdkbox.** { *; }
-dontwarn com.sdkbox.**

#twitter
-keep public com.twitter.sdk.android.** { *; }

Note: Proguard 只能工作在 Release 模式下（比如： cocos run -m release） debug 模式下不会触发 Proguard 。