一、前置准备（10 分钟搞定）
1. 注册极光账号并创建应用
- 访问极光推送官网，注册企业账号（个人账号也可测试）；
- 登录后进入「开发者中心」→「创建应用」，填写应用名称（如「员工周年祝福推送」），选择对应平台（Android/iOS/ 小程序，按需选）；
- 创建成功后，记录 3 个核心参数（后续开发必用）：
AppKey：应用唯一标识；Master Secret：服务端调用 API 的密钥（严禁泄露）；PackageName/Bundle ID：客户端包名 / 应用 ID（需和客户端配置一致）。
2. 环境依赖（服务端以 Java 为例）
极光推送支持 Java/Python/PHP 等主流语言，这里以 Java（SpringBoot）为例，添加 Maven 依赖：
XML
<!-- 极光推送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>二、服务端核心开发（最快 30 分钟实现推送）
1. 封装极光推送工具类（开箱即用）
创建JPushUtil，封装通用推送方法，适配「单推 / 批量推 / 按别名推」
java
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;
/**
* 极光推送工具类（适配员工周年/生日祝福推送）
*/
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. 构建推送载荷（Platform：推送平台，Audience：推送目标，Notification：消息内容）
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;
}
}2. 业务层调用（适配你的入职周年推送）
在消息推送 Job 中，调用上面的工具类：
java
// 示例：给入职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);
}
}三、客户端快速集成（以 Android 为例，iOS / 小程序同理）
1. Android 端核心步骤（Gradle 集成）
（1）添加依赖（build.gradle）
java
dependencies {
// 极光推送Android SDK
implementation 'cn.jiguang.sdk:jpush:4.8.1'
// 极光核心基础库
implementation 'cn.jiguang.sdk:jcore:2.6.1'
}（2）配置清单（AndroidManifest.xml）
XML
<!-- 替换成你的极光AppKey -->
<meta-data
android:name="JPUSH_APPKEY"
android:value="你的极光AppKey" />
<meta-data
android:name="JPUSH_CHANNEL"
android:value="developer-default" /> <!-- 渠道名，默认即可 -->（3）初始化 SDK（Application 中）
java
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);
}
}（4）接收推送消息（自定义 Receiver）
java
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);
}
}
}四、测试验证（关键步骤，确保能推通）
1. 测试环境配置
- 服务端：
IS_PRODUCTION = false（极光测试环境）； - 客户端：安装测试包（Android/iOS），确保设备联网；
- 绑定别名：客户端初始化时绑定的员工 ID，和服务端推送的 alias 一致。
2. 手动测试
- 调用服务端
pushByAlias方法，推送一条测试消息； - 客户端查看：通知栏是否收到消息，点击是否跳转；
- 极光后台验证：登录极光控制台→「推送记录」，查看推送状态（送达 / 点击数）。
3. 常见问题排查
| 问题 | 解决方案 |
|---|---|
| 推送失败：1001 | AppKey/Master Secret 错误，核对极光后台的参数 |
| 客户端收不到消息 | 1. 测试环境 / 生产环境不匹配；2. 别名绑定失败；3. 设备未联网 / 极光 SDK 未初始化 |
| iOS 收不到消息 | 开启 APNs 推送权限，配置推送证书（极光后台上传证书） |
五、核心优化建议（适配生产环境）
- 别名 / 标签规范 ：
- 别名：用「员工 ID」唯一标识（如
emp_10086），避免重复； - 标签：按部门 / 工龄分组（如
dept_tech、anniversary_5），便于批量推送。
- 别名：用「员工 ID」唯一标识（如
- 推送频率控制 ：
- 避免短时间批量推送（极光有频率限制），分批推送（如每次推 100 条）；
- 异常重试 ：
- 推送失败的消息（如网络异常），记录到数据库，定时重试；
- 数据统计 ：
- 对接极光的统计 API，统计推送送达率、点击率，优化推送策略。
总结
核心关键点
- 极光推送核心是「服务端发消息（API）+ 客户端收消息（SDK）」，通过「别名 / 标签」精准定位用户；
- 场景（员工周年 / 生日祝福）优先用「按别名推送」，确保每条消息精准推给对应员工；
- 测试时重点核对「环境（测试 / 生产）」「参数（AppKey / 别名）」「权限（客户端推送权限）」。
快速上手路径
- 注册极光账号→创建应用→获取 AppKey/Master Secret；
- 服务端集成 SDK，封装推送工具类；
- 客户端集成 SDK，绑定别名，接收消息；
- 测试推送，排查问题，上线。
按这个教程，1-2 小时就能完成从配置到测试的全流程。如果需要 iOS / 小程序的集成细节，或者批量推送的优化方案，可以 进一步了解。