一、使用说明

1.sdk声明
贴贴分享sdk作为一个桥梁，业务方通过sdk提供的接口跟小米互传通信。sdk内部不涉及任何敏感数据获取和敏感权限申请，只通过aidl跨进程通信接口实现业务交互。
2.调用线程说明
贴贴分享内部没有耗时逻辑，业务方在调用sdk注册和解注册接口时请在主线程中调用，sdk内部会切换到子线程中处理业务逻辑。
3.注册、解注册接口调用时机
sdk提供了分享注册接口和解注册接口，请在待分享页面的onResume/onStart方法中调用注册接口，在onPause/onStop方法中调用解注册接口。
4.数据发送接口
sdk提供了数据发送接口，在注册接口的回调中准备好待分享数据后，调用数据发送接口发送数据。
5.业务方取消分享接口
如果业务方因为自身原因无法提供待分享数据，请调用取消接口通知小米互传取消本次分享，同时由业务方负责错误提示。
6.互传取消回调接口
如果小米互传由于异常原因取消此次分享，会调用取消回调接口通知业务方，业务方取消准备待分享数据，同时由互传负责错误提示。
7.发送结果回调接口
小米互传会将本次分享结果通过接口回调给业务方（成功、失败），业务方按需使用（比如打点）。
8.TapShareRegisterBean数据结构
TapShareRegisterBean作为注册接口的参数，可以通过TapShareRegisterBean对象设置支持分享的平台信息，如果指定只支持跟小米设备分享，则跟苹果设备贴贴时不会触发贴贴分享功能。
9.TapShareSendBean数据接口
TapShareSendBean作为数据发送接口的参数，可以通过TapShareSendBean对象设置预览信息，包括预览图、标题、副标题。另外还可以通过TapShareSendBean对象设置透传参数（按需使用）
10.TapShareDataHandler数据接口
小米互传返回给业务方的数据对象，该对象中包含了对端的设备平台信息，业务方可以根据对端设备类型准备不同的分享数据。

二、开发流程

三、使用约束

1.注册和解注册接口调用线程要求在主线程。
2.在activity生命周期方法中调用注册、解注册接口
详情参考5.1使用说明

四、开发步骤

1、添加App Id 和构建版本 Debug 标识

• App Id
  com.xiaomi.xms.APP_ID
  当开通服务时，会生成 App Id 唯一标识，用于鉴权
  必须配置 App Id，调用服务时会通过 App Id 进行鉴权
• 构建版本 Debug 标识
  com.xiaomi.xms.BUILD_TYPE_DEBUG
  当前 APK 是否为 Debug 构建版本。若不配置，默认为 false

（鉴权时会验证应用 apk 签名。开发调试阶段，一般不会运行 Release 签名的 apk，通常都是运行 Debug 签名 apk，为了保证在开发阶段仍然可以鉴权成功，开发者可以在平台同时添加正式证书指纹（Release 签名）和测试证书指纹（Debug 签名），用于不同场景下鉴权。）

• 在应用的 AndroidManifest.xml 中添加 meta-data 配置

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
       
        <meta-data
            android:name="com.xiaomi.xms.APP_ID"
            android:value="your app id here" />
            
        <meta-data
            android:name="com.xiaomi.xms.BUILD_TYPE_DEBUG"
            android:value="true or false" />
   
    </application>
</manifest>

2、在Android Studio中引用aar文件

贴贴分享sdk以aar文件的形式提供，请将aar文件放置在模块内的libs目录中，并在build.gradle文件中配置引用。

fileTree(dir: 'libs', include: ['*.aar']).each { aarFile ->  
    implementation files(aarFile) 
}

3、按照接口说明调用相关接口

在对应的场景调用贴贴分享相关接口，并提供对应数据即可。

3.1 在onResume/onStart方法调用注册接口

TapShareManager.getInstance().registerSendCallback(this, mTapShareSendCallback);

3.2 在onPause/onStop方法调用解注册接口

TapShareManager.getInstance().unregisterSendCallback(this, mTapShareSendCallback);

3.3 在注册接口回调中调用数据发送接口

private TapShareSendCallback mTapShareSendCallback = new TapShareSendCallback() {
    @Override
    public void onTapShareSend(TapShareDataHandler handler) {
        new Thread(new Runnable() {
            @Override
            public void run() {
                // 业务方准备数据
                if (可以提供发送数据) {
                    // 准备数据
                    List<Uri> uris = null;
                    TapShareSendBean tapShareSendBean = new TapShareSendBean.Builder().
                    setPreviewInfo(uri, title, subTitle). // 传输中预览数据，分别为缩略图uri，标题，副标题
                    setReceiveAction("业务方自定义action或原生跳转action"). // 对端为android平台时，使用包名 + action响应，一方应用传输到ios平台时，由互传代为解决跨平台兼容性
                    setReceiveExtendParam("extendParam"). // 可选扩展参数，接入方可透传到接收时辅助接收响应
                    build();
                    // 调用对应接口发送数据
                    //对于传文件uri的应用，调用sendByUri接口
                    handler.sendByUri(uris, tapShareSendBean); 
                    //浏览器应用和wifi应用，调用sendByString接口，直接传string即可
                    handler.sendByString("", tapShareSendBean); 
                } else {
                    // 种种原因无法提供数据
                    handler.cancelSend(1, "");
                }
            }
        }).start(); 
    }

五、调测验证

每个接口调用都会有返回值，如果返回值为0，则表示接口成功调用，其他值则表示调用异常，具体请参考错误码。

六、接口说明/API参考文档/调用方式说明

1、API接口文档

发送端相关接口说明

• TapShareManager接口，由业务方负责调用，业务方通知互传分享状态。

• TapShareRegisterBean数据结构:
  
• 业务方提供支持分享的平台信息

List<Integer> platformList = new ArrayList<>();
platformList.add(TapShareConstant.SupportedPlatform.ANDROID_MI_PHONE); //支持小米分享小米
platformList.add(TapShareConstant.SupportedPlatform.IOS_IPHONE); //支持小米分享苹果

TapShareRegisterBean registerBean = new TapShareRegisterBean();
registerBean.setSupportSharedPlatforms(platformList);
TapShareManager.getInstance().registerSendCallback(getActivity(), registerBean, mTapShareSendCallback);

• TapShareSendCallback回调接口，贴贴事件发生后的回调接口，互传通知业务方贴贴状态

• TapShareDataHandler接口，获取本次贴贴事件相关信息和发送数据接口，业务方发送待分享数据

• TapShareSendBean数据结构，提供贴贴分享后续交互所需的信息:
• 传输中的预览数据
• 传输完成的响应数据

TapShareSendBean builder = new TapShareSendBean.Builder().
        setPreviewInfo(uri, title, subTitle). // 传输中预览数据
        setReceiveExtendParam("extendParam"). // 可选扩展参数，接入方可透传到接收时辅助接收响应，按需使用
        build();

预览图说明

• uri：预览图的uri， 预览图大小同卡片大小（底部覆盖透明色上有标题、副标题、裁切方式centerCrop,如下图）
• title：主标题，最多不超过两行，超出截断显示
• subTitle：副标题，最多一行，超出截断显示

发送方示例伪代码

@Override
protected void onResume() {
    super.onResume();
    List<Integer> platformList = new ArrayList<>();
    platformList.add(TapShareConstant.SupportedPlatform.ANDROID_MI_PHONE); //支持小米分享小米
    platformList.add(TapShareConstant.SupportedPlatform.IOS_IPHONE); //支持小米分享苹果
    
    TapShareRegisterBean registerBean = new TapShareRegisterBean();
    registerBean.setSupportSharedPlatforms(platformList);
    TapShareManager.getInstance().registerSendCallback(this, registerBean, mTapShareSendCallback);
}

@Override
protected void onPause() {
    TapShareManager.getInstance().unregisterSendCallback(this, mTapShareSendCallback);
    super.onPause();
}

private TapShareSendCallback mTapShareSendCallback = new TapShareSendCallback() {
    @Override
    public void onTapShareSend(TapShareDataHandler handler) {
        new Thread(new Runnable() {
            @Override
            public void run() {
                // 业务方准备数据
                if (可以提供发送数据) {
                    // 准备数据
                    List<Uri> uris = null;
                    TapShareSendBean tapShareSendBean = new TapShareSendBean.Builder().
                    setPreviewInfo(uri, title, subTitle). // 传输中预览数据，分别为缩略图uri，标题，副标题
                    setReceiveExtendParam("extendParam"). // 可选扩展参数，接入方可透传到接收时辅助接收响应
                    build();
                    // 调用对应接口发送数据
                    handler.sendByString(“appLink”, tapShareSendBean);
                } else {
                    // 无法提供数据，调用取消发送接口
                    handler.cancelSend(1, "");
                }
            }
        }).start(); 
    }

    @Override
    public void onTapShareCancel(TapShareDataHandler handler) {
        // 互传通知业务方本次发送取消，业务方取消数据准备
    }
    
    @Override
    public void onSendResult(int sendResult) {
        // 互传通知业务方本次发送结果
    }
};

接收端互传打开业务方应用
互传在接收端通过appLink直接打开业务方应用，业务方处理后续逻辑

• 注：如果接收端应用不存在，互传会跳转到应用商店

Uri uri = Uri.parse("appLink");
intent = new Intent(Intent.ACTION_VIEW, uri);
intent.setPackageName("应用包名，由互传自动获取")
startActivity(intent);

2、错误码

public interface ErrorCode {
    int METHOD_CALL_SUCCEED = 0; // 调用成功
    int WINDOW_SPECIAL_STATES = 1; // 特殊窗口
    int CALLBACK_NOT_MATCH = 2; // callback不一致
    int METHOD_CALL_INVALID = 3; // 调用非法
    int METHOD_PARAM_INVALID = 4; // 参数异常
}