Java大前端java
极光推送（JPush）快速上手：Java 后端与全平台适配
本文详解极光推送（JPush）的集成方案，包含服务端 Java 代码实现与客户端 Android/iOS 适配步骤。核心内容涉及应用创建、SDK 依赖引入、推送工具类封装、别名精准推送逻辑及客户端消息接收处理。同时提供测试验证流程、常见错误排查表及生产环境下的频率控制与异常重试优化建议，助力开发者快速构建稳定推送服务。
本文详解极光推送（JPush）的集成方案，包含服务端 Java 代码实现与客户端 Android/iOS 适配步骤。核心内容涉及应用创建、SDK 依赖引入、推送工具类封装、别名精准推送逻辑及客户端消息接收处理。同时提供测试验证流程、常见错误排查表及生产环境下的频率控制与异常重试优化建议，助力开发者快速构建稳定推送服务。
AppKey：应用唯一标识；Master Secret：服务端调用 API 的密钥（严禁泄露）；PackageName/Bundle ID：客户端包名 / 应用 ID（需和客户端配置一致）。极光推送支持 Java/Python/PHP 等主流语言，这里以 Java（SpringBoot）为例，添加 Maven 依赖：
<!-- 极光推送 Java SDK（最新版） -->
<dependency>
<groupId>cn.jpush.api</groupId>
<artifactId>jpush-client</artifactId>
<version>3.8.16</version>
</dependency>
<!-- 依赖的 JSON 工具 -->
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.9</version>
</dependency>
创建 JPushUtil，封装通用推送方法，适配「单推 / 批量推 / 按别名推」。
import cn.jpush.api.JPushClient;
import cn.jpush.api.push.PushResult;
import cn.jpush.api.push.model.Platform;
import cn.jpush.api.push.model.PushPayload;
import cn.jpush.api.push.model.audience.Audience;
import cn.jpush.api.push.model.notification.Notification;
import cn.jpush.api.common.resp.APIConnectionException;
import cn.jpush.api.common.resp.APIRequestException;
import java.util.List;
/**
* 极光推送工具类（适配员工周年/生日祝福推送）
*/
public class JPushUtil {
// 替换成你的 AppKey 和 Master Secret
private static final String APP_KEY = "你的极光 AppKey";
private static final String MASTER_SECRET = "你的极光 Master Secret";
// 生产环境/测试环境开关（测试用 false，上线改 true）
private static final boolean IS_PRODUCTION = false;
/**
* 按别名推送（推荐：员工 ID 作为别名，精准推送给单个员工）
* @param alias 员工 ID（唯一标识，如"emp_10086"）
* @param title 消息标题（如"入职 5 周年祝福"）
* @param content 消息内容（如"恭喜您入职满 5 周年！"）
* @return 推送结果
*/
public static PushResult pushByAlias(String alias, String title, String content) {
// 1. 创建 JPush 客户端
JPushClient jpushClient = new JPushClient(MASTER_SECRET, APP_KEY);
try {
// 2. 构建推送载荷
PushPayload payload = PushPayload.newBuilder()
// 推送平台：all=安卓+iOS，也可指定 Android/iOS
.setPlatform(Platform.all())
// 推送目标：按别名推（alias 是员工唯一标识）
.setAudience(Audience.alias(alias))
// 消息内容：通知栏消息（支持自定义字段）
.setNotification(Notification.alert(content)
.addPlatformNotification(
cn.jpush.api.push.model.notification.AndroidNotification.newBuilder()
.setTitle(title)
// 自定义字段：便于客户端解析（如周年数、消息类型）
.addExtra("anniversary_year", "5")
.addExtra("msg_type", "work_anniversary")
.build()
)
.addPlatformNotification(
cn.jpush.api.push.model.notification.IosNotification.newBuilder()
.setAlert(content)
.setBadge(1) // iOS 角标 +1
.setSound("default") // 提示音
.build()
)
)
// 环境配置：测试环境（false）/生产环境（true）
.setOptions(
cn.jpush.api.push.model.Options.newBuilder()
.setApnsProduction(IS_PRODUCTION)
.build()
)
.build();
// 3. 执行推送
PushResult result = jpushClient.sendPush(payload);
System.out.println("推送成功：" + result);
return result;
} catch (APIConnectionException e) {
// 网络异常
System.err.println("推送失败：网络连接异常");
e.printStackTrace();
} catch (APIRequestException e) {
// API 调用异常（如 AppKey 错误、参数非法）
System.err.println("推送失败：" + e.getErrorCode() + " - " + e.getErrorMessage());
e.printStackTrace();
} finally {
// 关闭客户端
jpushClient.close();
}
return null;
}
/**
* 批量推送（适配一次性推送给多个员工）
* @param aliasList 员工 ID 列表（如["emp_10086", "emp_10087"]）
* @param title 标题
* @param content 内容
* @return 推送结果
*/
public static PushResult pushByAliasList(List<String> aliasList, String title, String content) {
JPushClient jpushClient = new JPushClient(MASTER_SECRET, APP_KEY);
try {
PushPayload payload = PushPayload.newBuilder()
.setPlatform(Platform.all())
.setAudience(Audience.alias(aliasList)) // 批量别名
.setNotification(Notification.alert(content)
.addPlatformNotification(
cn.jpush.api.push.model.notification.AndroidNotification.newBuilder()
.setTitle(title)
.build()
)
)
.setOptions(cn.jpush.api.push.model.Options.newBuilder()
.setApnsProduction(IS_PRODUCTION)
.build())
.build();
PushResult result = jpushClient.sendPush(payload);
System.out.println("批量推送成功：" + result);
return result;
} catch (Exception e) {
e.printStackTrace();
} finally {
jpushClient.close();
}
return null;
}
}
在消息推送 Job 中，调用上面的工具类：
// 示例：给入职 5 周年的员工推送祝福
public void pushWorkAnniversaryMessage() {
// 1. 筛选出符合条件的员工（调用你之前的 diffYear 方法）
List<Employee> employeeList = employeeService.listByAnniversary(5);
for (Employee emp : employeeList) {
// 2. 员工 ID 作为极光推送的别名（确保唯一）
String alias = "emp_" + emp.getId();
// 3. 组装祝福内容
String title = "入职 5 周年祝福";
String content = "尊敬的" + emp.getName() + "：恭喜您入职满 5 周年，感谢您的一路相伴！";
// 4. 调用极光推送
JPushUtil.pushByAlias(alias, title, content);
}
}
dependencies {
// 极光推送 Android SDK
implementation 'cn.jiguang.sdk:jpush:4.8.1'
// 极光核心基础库
implementation 'cn.jiguang.sdk:jcore:2.6.1'
}
<!-- 替换成你的极光 AppKey -->
<meta-data android:name="JPUSH_APPKEY" android:value="你的极光 AppKey" />
<meta-data android:name="JPUSH_CHANNEL" android:value="developer-default" />
<!-- 渠道名，默认即可 -->
public class MyApp extends Application {
@Override
public void onCreate() {
super.onCreate();
// 初始化极光推送
JPushInterface.setDebugMode(true); // 测试模式，上线关闭
JPushInterface.init(this);
// 绑定别名（员工 ID），确保服务端能精准推送
String employeeId = "emp_10086"; // 从本地/接口获取员工ID
JPushInterface.setAlias(this, 0, employeeId);
}
}
public class JPushReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
Bundle bundle = intent.getExtras();
if (JPushInterface.ACTION_NOTIFICATION_RECEIVED.equals(intent.getAction())) {
// 接收通知栏消息
String title = bundle.getString(JPushInterface.EXTRA_NOTIFICATION_TITLE);
String content = bundle.getString(JPushInterface.EXTRA_ALERT);
// 解析自定义字段（如周年数）
String anniversaryYear = bundle.getString("anniversary_year");
System.out.println("收到周年祝福：" + title + " - " + content + "，周年数：" + anniversaryYear);
} else if (JPushInterface.ACTION_NOTIFICATION_OPENED.equals(intent.getAction())) {
// 点击通知栏跳转
Intent jumpIntent = new Intent(context, AnniversaryDetailActivity.class);
jumpIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
context.startActivity(jumpIntent);
}
}
}
IS_PRODUCTION = false（极光测试环境）；pushByAlias 方法，推送一条测试消息；| 问题 | 解决方案 |
|---|---|
| 推送失败：1001 | AppKey/Master Secret 错误，核对极光后台的参数 |
| 客户端收不到消息 | 1. 测试环境 / 生产环境不匹配；2. 别名绑定失败；3. 设备未联网 / 极光 SDK 未初始化 |
| iOS 收不到消息 | 开启 APNs 推送权限，配置推送证书（极光后台上传证书） |
emp_10086），避免重复；dept_tech、anniversary_5），便于批量推送。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online