# Android 接入指南

微信 Open SDK for Android 是微信开放平台面向 Android 端第三方应用提供的开发工具包，支持分享与收藏、微信登录、微信支付等能力。本文档面向已具备 Android Studio（或 Eclipse）基本使用经验的开发者，介绍 Open SDK 的接入与使用方法。

**注 1：接入 Open SDK 的开发者，请先认真阅读[《微信 Open SDK 个人信息处理规则》](https://support.weixin.qq.com/cgi-bin/mmsupportacctnodeweb-bin/pages/RYiYJkLOrQwu0nb8)及[《微信 Open SDK 开发者合规使用指南》](/doc/oplatform/Mobile_App/agreement/sdk)，并确保对 OpenSDK 的接入使用情况符合上述指南中的相关要求。**

**注 2：jCenter 服务将在 2021 年 5 月 1 日之后关停，微信 SDK 已迁移到 Maven Central，请开发者及时修改引用仓库。**

**注 3：微信 SDK 已迁移到 Maven Central 发布，包名从原来的 `com.tencent.mm.sdk` 修改为 `com.tencent.mm.opensdk`，需要开发者同步修改对应的 import 语句。**

**注 4：本文为微信 Android 终端开发工具的新手使用教程，只涉及教授 SDK 的使用方法，默认读者已经熟悉 IDE 的基本使用方法（Android Studio（推荐）或 Eclipse），以及具有一定的编程知识基础等。**

**注 5：Open SDK for Android 的资源可前往[《微信Open SDK for Android》](/doc/oplatform/Mobile_App/Downloads/Android_Resource)下载。**

注意：Eclipse 是 Google 已停止维护的开发工具，新接入项目建议直接使用 Android Studio。

## 关于 OpenSDK 6.8.0 的更新说明

微信将于近期发布 targetSdkVersion 30 的客户端版本，**因 Android 11 系统特性，该微信版本在 Android 11 及以上系统版本的设备上运行时，授权登录、分享、微信支付等功能受到影响，可能无法正常使用**。为了适配 Android 系统新版本特性，保证微信功能正常使用，请第三方应用**2021 年 11 月 1 日之前**进行更新，点击查看更新指引。

**目录**

- 接入指南
- Android 11 更新 OpenSDK 适配
- Android 13 可能存在的问题适配

## 接入指南

### 1. 申请你的 AppID

请到开发者应用登记页面进行登记，登记并选择移动应用进行设置后，将该应用提交审核，只有审核通过的应用才能进行开发。

### 2. 下载 SDK 及 API 文档

**Android Studio 环境下：**

在 `build.gradle` 文件中，添加如下依赖即可：

```groovy
dependencies {
    api 'com.tencent.mm.opensdk:wechat-sdk-android:+'
}
```

（从 6.8.0 版本开始，请使用 `wechat-sdk-android`）

由于 jCenter 服务关停，需要修改成引用 Maven Central，在项目的根 `build.gradle` 文件中，添加如下代码即可：

```groovy
buildscript {
    repositories {
        jcenter()       // 原有 jCenter 引用可继续保留
        mavenCentral()
    }
}

allprojects {
    repositories {
        jcenter()      // 原有 jCenter 引用可继续保留
        mavenCentral()
    }
}
```

**特别注意，目前 Maven Central 仅支持部分版本：6.6.4、6.6.5、6.6.23、6.7.0、6.7.9、6.8.0，建议开发者升级至最新版本 6.8.0。后续所有版本更新都会上传至 Maven Central。**

**Eclipse 环境下：**

请前往[《微信Open SDK for Android》](/doc/oplatform/Mobile_App/Downloads/Android_Resource) 下载最新 SDK 包。

### 3. 搭建开发环境

**Android Studio 环境下：**

在 Android Studio 中新建你的工程，并保证网络设置可以成功从 Maven Central 下载微信 SDK 即可。

**Eclipse 环境下：**

1）在 Eclipse 中建立你的工程。

2）在工程中新建一个 libs 目录，将开发工具包中 libs 目录下的 `libammsdk.jar` 复制到该目录中（如下图所示，建立了一个名为 SDK_Sample 的工程，并把 jar 包复制到 libs 目录下）。

![](https://res.wx.qq.com/op_res/yXeM-qkPNMo3NZ6AOSZ0x8MqkBf9ATOfaw-2Ic93vUG8xFid8niGKr3W_RfCmMxe)

3）右键单击工程，选择「Build Path」中的「Configure Build Path...」，选中「Libraries」这个 tab，并通过「Add Jars...」导入工程 libs 目录下的 `libammsdk.jar` 文件（如下图所示）。

![](https://res.wx.qq.com/op_res/AcZSyJLkQzLTjKChk8gLiJZok4cRD8b2OnpCH--OcGDexwEgscrauV7ZkLqsHNKs)

在你需要使用微信终端 API 的文件中导入相应的类：

```java
import com.tencent.mm.opensdk.openapi.WXTextObject;
```

### 4. 在代码中使用开发工具包

**1）注册到微信**

要使你的程序启动后微信终端能响应你的程序，必须在代码中向微信终端注册你的 id。可以在程序入口 Activity 的 `onCreate` 回调函数处，或其他合适的地方将你的应用 id 注册到微信。注册函数示例如下：

```java
// APP_ID 替换为你的应用从官方网站申请到的合法 appID
private static final String APP_ID = "wx88888888";

// IWXAPI 是第三方 app 和微信通信的 openApi 接口
private IWXAPI api;

private regToWx() {
    // 通过 WXAPIFactory 工厂，获取 IWXAPI 的实例
    api = WXAPIFactory.createWXAPI(this, APP_ID, true);

    // 将应用的 appId 注册到微信
    api.registerApp(APP_ID);

    // 建议动态监听微信启动广播进行注册到微信
    registerReceiver(new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            // 将该 app 注册到微信
            api.registerApp(Constants.APP_ID);
        }
    }, new IntentFilter(ConstantsAPI.ACTION_REFRESH_WXAPP));
}
```

**2）发送请求或响应到微信**

现在，你的程序要发送请求或发送响应到微信终端，可以通过 IWXAPI 的 `sendReq` 和 `sendResp` 两个方法来实现。

- `boolean sendReq(BaseReq req);`：第三方 app 主动发送消息给微信，发送完成之后会切回到第三方 app 界面
- `boolean sendResp(BaseResp resp);`：微信向第三方 app 请求数据，第三方 app 回应数据之后会切回到微信界面

**sendReq 的实现示例：**

```java
// 初始化一个 WXTextObject 对象，填写分享的文本内容
WXTextObject textObj = new WXTextObject();
textObj.text = text;

// 用 WXTextObject 对象初始化一个 WXMediaMessage 对象
WXMediaMessage msg = new WXMediaMessage();
msg.mediaObject = textObj;
msg.description = text;

SendMessageToWX.Req req = new SendMessageToWX.Req();
req.transaction = String.valueOf(System.currentTimeMillis());  // transaction 字段用于唯一标识一个请求
req.message = msg;
req.scene = mTargetScene;

// 调用 api 接口，发送数据到微信
api.sendReq(req);
```

需要注意的是，`SendMessageToWX.Req` 的 `scene` 成员：

- 如果 scene 填 `WXSceneSession`，消息会发送至微信的会话内
- 如果 scene 填 `WXSceneTimeline`（微信 4.2 以上支持），消息会发送至朋友圈
- scene 默认值为 `WXSceneSession`

`com.tencent.mm.opensdk.constants.Build.java` 里面定义了各个功能支持的版本号，如果需要检查微信版本支持 API 的情况，可调用 IWXAPI 的 `getWXAppSupportAPI` 方法。比如，要判断微信是否支持分享到朋友圈功能：

```java
if (api.getWXAppSupportAPI() >= Build.TIMELINE_SUPPORTED_SDK_INT) {
    // do share
}
```

**sendResp 的实现示例：**

```java
// 初始化一个 WXTextObject 对象
WXTextObject textObj = new WXTextObject();
textObj.text = text;

// 用 WXTextObject 对象初始化一个 WXMediaMessage 对象
WXMediaMessage msg = new WXMediaMessage(textObj);
msg.description = text;

// 构造一个 Resp
GetMessageFromWX.Resp resp = new GetMessageFromWX.Resp();
// 将 req 的 transaction 设置到 resp 对象中
// 其中 bundle 为微信传递过来的 Intent 所带的内容，通过 getExtras() 方法获取
resp.transaction = new GetMessageFromWX.Req(bundle).transaction;
resp.message = msg;

// 调用 api 接口，发送数据到微信
api.sendResp(resp);
```

具体要发送的内容由第三方 app 开发者定义，具体可参考微信开发工具包中的 SDK Sample Demo 源码。

**3）接收微信的请求及返回值**

如果你的程序需要接收微信发送的请求，或者接收发送到微信请求的响应结果，需要下面 3 步操作：

**a.** 在你的包名相应目录下新建一个 wxapi 目录，并在该 wxapi 目录下新增一个 `WXEntryActivity` 类，该类继承自 Activity（例如应用程序的包名为 `net.sourceforge.simcpux`，则新添加的类如下图所示）：

![](https://res.wx.qq.com/op_res/Slhlj6swB6wxuVgHYiyFAJa1M77_LqUfrgxyE6rY7chhiOm4_HmUWKdmpyiGIOAI)

并在 manifest 文件里面加上 `exported`、`taskAffinity` 及 `launchMode` 属性，其中 `exported` 设置为 `true`，`taskAffinity` 设置为你的包名，`launchMode` 设置为 `singleTask`，例如：

```xml
<activity
    android:name=".wxapi.WXEntryActivity"
    android:label="@string/app_name"
    android:theme="@android:style/Theme.Translucent.NoTitleBar"
    android:exported="true"
    android:taskAffinity="填写你的包名"
    android:launchMode="singleTask">
</activity>
```

**b.** 实现 `IWXAPIEventHandler` 接口，微信发送的请求将回调到 `onReq` 方法，发送到微信请求的响应结果将回调到 `onResp` 方法。

**c.** 在 `WXEntryActivity` 中将接收到的 intent 及实现了 `IWXAPIEventHandler` 接口的对象传递给 IWXAPI 接口的 `handleIntent` 方法，示例如下：

```java
api.handleIntent(getIntent(), this);
```

当微信发送请求到你的应用，将通过 `IWXAPIEventHandler` 接口的 `onReq` 方法进行回调，类似的，应用请求微信的响应结果将通过 `onResp` 回调。

**注意事项**

1）如果需要混淆代码，为了保证 SDK 的正常使用，需要在 `proguard.cfg` 加上下面配置：

```
-keep class com.tencent.mm.opensdk.** {
    *;
}

-keep class com.tencent.wxop.** {
    *;
}

-keep class com.tencent.mm.sdk.** {
    *;
}
```

2）如果需要运行 SDK Sample 工程，需要通过指定的 `debug.keystore` 来进行签名：

Android Studio 环境下：

```groovy
signingConfigs {
    debug {
        storeFile file("../debug.keystore")
    }
}
```

Eclipse 环境下：

请查阅文档[《如何运行 SDK Demo 工程》](https://open.weixin.qq.com/zh_CN/htmledition/res/assets/run-android-sdk-sample.doc)。

至此，你已经能使用微信 Android 开发工具包的 API 内容了。如果想更详细了解每个 API 函数的用法，请查阅 Android 平台参考手册或自行下载阅读微信 SDK Sample Demo 源码。

[前往下载《微信Open SDK for Android》](/doc/oplatform/Mobile_App/Downloads/Android_Resource)

## Android 11 更新 OpenSDK 适配

针对微信 targetSdkVersion 30 的客户端版本，**因 Android 11 系统特性，该微信版本在 Android 11 及以上系统版本的设备上运行时，授权登录、分享、微信支付等功能受到影响，可能无法正常使用**。为了适配 Android 系统新版本特性，保证微信功能正常使用，请第三方应用**2021 年 11 月 1 日之前**进行如下更新：

### 适配方案

**1）第三方应用需要更新微信 Android SDK 至 6.8.0 版本**，引用代码如下：

```groovy
dependencies {
    api 'com.tencent.mm.opensdk:wechat-sdk-android:6.8.0'
    // 或者直接引用最新版本
    // api 'com.tencent.mm.opensdk:wechat-sdk-android:+'
}
```

无论第三方应用 targetSdkVersion 是否升级为 30，均需要进行微信 Android SDK 版本升级适配。

**2）targetSdkVersion 升级到 30 的第三方应用**，由于 Android 11 [软件包可见性](https://developer.android.com/preview/privacy/package-visibility) 特性的影响，**OpenSDK 的接口可能无法正常拉起微信，从而无法使用微信的部分功能**，需要在主工程的 `AndroidManifest.xml` 中增加标签，代码如下：

```xml
<manifest package="com.example.app">

      ...

      // 在应用的 AndroidManifest.xml 添加如下 <queries> 标签
    <queries>
        <package android:name="com.tencent.mm" />   // 指定微信包名
    </queries>

      ...

</manifest>
```

注：添加以上标签之后，需要开发者升级编译工具，否则会出现编译错误。

- Android Studio 需要**升级至 3.3 及以上，建议升级至 4.0 及以上版本**
- Android SDK Build-Tools 需要**升级至 30 及以上版本**
- `com.android.tools.build:gradle` **需要升级至 3.6.0 版本及以上**

### 验证流程

**1）环境准备：**

- 系统：Android 11 及以上
- 微信：[下载 target30 测试版微信](https://dldir1.qq.com/weixin/android/amm_app_target30_test.apk)
- 第三方应用：已按照步骤 1 和 2 更新 OpenSDK

**2）验证步骤：**

1）安装第三方应用后，首次触发微信登录功能（注：该操作前务必不要触发任何分享、跳转等 OpenSDK 功能）

2）若成功完成微信登录功能，即验证 OpenSDK 更新成功

3）若签名验证失败，收到回调 `errcode=-6`，则需开发者重新检查步骤 1 和 2 是否完成

targetSdkVersion 升级到 30 的第三方应用，具体适配详情另可参考文档 [Android 11 系统策略更新，请开发者及时适配](https://open.weixin.qq.com/cgi-bin/announce?action=getannouncement&key=11600155960jI9EY&version=&lang=&token=)。

## Android 13 可能存在的问题适配

### 1. Intent-filter 导致的无法回跳问题

**存在的问题**

Android 13 开始 Intent 过滤器会屏蔽不匹配的 intent。详见 Android 官网：[Android 13 变更说明](https://developer.android.com/about/versions/13/behavior-changes-all?hl=zh-cn#intents)

因此如果：

- 开发者在 Manifest 内声明 `WXEntryActivity` 时，添加了 intent-filter
- 开发者的 APP 运行在 Android 13 的手机上

**当满足以上两个条件时，微信内可能将无法回跳到第三方 App。**

**解决办法**

在 manifest 中，尝试去除 `WXEntryActivity` 的 intent-filter。具体写法应该遵照上面接入方案中提到的示例，如下：

```xml
<activity
    android:name=".wxapi.WXEntryActivity"
    android:label="@string/app_name"
    android:theme="@android:style/Theme.Translucent.NoTitleBar"
    android:exported="true"
    android:taskAffinity="填写你的包名"
    android:launchMode="singleTask">
</activity>
```