{"id":13471156,"url":"https://github.com/jpush/jpush-api-java-client","last_synced_at":"2025-05-14T02:08:55.507Z","repository":{"id":11201540,"uuid":"13585181","full_name":"jpush/jpush-api-java-client","owner":"jpush","description":"JiGuang's officially supported Java client library for accessing JPush APIs.   极光官方支持的 Java 版本服务器端 SDK。","archived":false,"fork":false,"pushed_at":"2024-11-12T03:56:58.000Z","size":16993,"stargazers_count":729,"open_issues_count":23,"forks_count":418,"subscribers_count":81,"default_branch":"master","last_synced_at":"2025-04-14T04:58:25.504Z","etag":null,"topics":["jpush","sdk-java"],"latest_commit_sha":null,"homepage":"https://docs.jiguang.cn","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jpush.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-10-15T09:01:25.000Z","updated_at":"2024-11-26T08:50:22.000Z","dependencies_parsed_at":"2024-01-15T20:57:59.053Z","dependency_job_id":"097d9fd7-6e48-4f1c-8001-babd193bcb53","html_url":"https://github.com/jpush/jpush-api-java-client","commit_stats":null,"previous_names":[],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpush%2Fjpush-api-java-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpush%2Fjpush-api-java-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpush%2Fjpush-api-java-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpush%2Fjpush-api-java-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpush","download_url":"https://codeload.github.com/jpush/jpush-api-java-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254053222,"owners_count":22006717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jpush","sdk-java"],"created_at":"2024-07-31T16:00:40.704Z","updated_at":"2025-05-14T02:08:50.492Z","avatar_url":"https://github.com/jpush.png","language":"Java","readme":"# 新版 SDK\n欢迎使用新一代 [jiguang-sdk-java](https://github.com/jpush/jiguang-sdk-java)！这个 SDK 旨在提供更好的性能、更多功能和更好的用户体验。\n\n为什么升级？\n* 性能优化：新版本经过优化，运行更快，消耗更少的资源。\n* 功能增强：引入了许多新功能和改进，使您的开发工作更加高效。\n* Bug 修复：解决了上个版本存在的问题，提高了稳定性和可靠性。\n\n\u003e 极光已推出新版本的 SDK 供广大用户使用，当前版本后续将不推荐使用，请移步仓库 [jiguang-sdk-java](https://github.com/jpush/jiguang-sdk-java) 了解更多。\n\n# ~~旧版 SDK~~\n\n[![GitHub version](https://badge.fury.io/gh/jpush%2Fjpush-api-java-client.svg)](http://badge.fury.io/gh/jpush%2Fjpush-api-java-client)\n\n# JPush API Java Library\n\n## 概述\n\n这是 JPush REST API 的 Java 版本封装开发包，是由极光推送官方提供的，一般支持最新的 API 功能。\n\n对应的 REST API 文档：[REST API - Push](https://docs.jiguang.cn/jpush/server/push/rest_api_v3_push/), [REST API - Report](https://docs.jiguang.cn/jpush/server/push/rest_api_v3_report/).\n\n版本更新：[Release页面](https://github.com/jpush/jpush-api-java-client/releases)。下载更新请到这里。\n\n\u003e 非常欢迎各位开发者提交代码，贡献一份力量，review过有效的代码将会合入本项目。\n\n\n## 安装\n\n### 依赖包\n* [jiguang-java-client-common](https://github.com/jpush/jiguang-java-client-common) / 极光 Java client 的公共封装开发包，必须依赖，v1.1.11 为例，查看[最新版本](https://github.com/jpush/jiguang-java-client-common/releases)\n* [slf4j](http://www.slf4j.org/) / log4j (Logger)\n* [gson](https://code.google.com/p/google-gson/) (Google JSON Utils)\n\n\u003e 其中 slf4j 可以与 logback, log4j, commons-logging 等日志框架一起工作，可根据你的需要配置使用。\n\n如果使用 Maven 构建项目，则需要在你的项目 pom.xml 里增加：\n\n```Java\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecn.jpush.api\u003c/groupId\u003e\n        \u003cartifactId\u003ejiguang-common\u003c/artifactId\u003e\n        \u003cversion\u003e1.1.11\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.netty\u003c/groupId\u003e\n        \u003cartifactId\u003enetty-all\u003c/artifactId\u003e\n        \u003cversion\u003e4.1.6.Final\u003c/version\u003e\n        \u003cscope\u003ecompile\u003c/scope\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.google.code.gson\u003c/groupId\u003e\n        \u003cartifactId\u003egson\u003c/artifactId\u003e\n        \u003cversion\u003e2.3\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.slf4j\u003c/groupId\u003e\n        \u003cartifactId\u003eslf4j-api\u003c/artifactId\u003e\n        \u003cversion\u003e1.7.7\u003c/version\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- For log4j --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.slf4j\u003c/groupId\u003e\n        \u003cartifactId\u003eslf4j-log4j12\u003c/artifactId\u003e\n        \u003cversion\u003e1.7.7\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003elog4j\u003c/groupId\u003e\n        \u003cartifactId\u003elog4j\u003c/artifactId\u003e\n        \u003cversion\u003e1.2.17\u003c/version\u003e\n    \u003c/dependency\u003e\n```\n\n如果不使用 Maven 构建项目，则项目 libs/ 目录下有依赖的 jar 可复制到你的项目里去。\n\n## 编译源码\n\n\u003e 如果开发者想基于本项目做一些扩展的开发，或者想了解本项目源码，可以参考此章，否则可略过此章。\n\n### 导入本项目\n\n* 可以采用 `git clone https://github.com/jpush/jpush-api-java-client.git jpush-api-src` 命令下载源码\n* 如果不使用git，请到[Release页面](https://github.com/jpush/jpush-api-java-client/releases)下载源码包并解压\n* 采用eclipse导入下载的源码工程，推荐采用maven的方式，方便依赖包的管理\n* 假如采用导入普通项目的方式，项目报错，检查Build Path，Libraries\n * 依赖jar包都在libs目录下可以找到，没有加入的请添加到Build Path，Libraries\n * 默认采用了log4j做日志框架，开发者可根据自己需求替换logback、commons-logging等日志框架\n * 极个别情况下，如果test目录报错，请手动添加test的依赖jar包mockwebserver-2.0.0.jar、okhttp-2.0.0.jar、okio-1.0.0.jar\n* 开发者需要注意，将本项目的编码格式设置为UTF-8\n\n### 构建本项目\n\n可以用 Eclipse 类 IDE 导出 jar 包。建议直接使用 maven，执行命令：\n\n\tmvn package\n\n### 自动化测试\n\n在项目目录下执行命令：\n\n\tmvn test\n\n## 使用样例\n如果使用 NettyHttpClient(v3.2.15 版本新增），需要在响应返回后手动调用一下 NettyHttpClient 中的 close 方法，否则进程不会退出。代码示例：\n```\n...\ntry {\n    PushResult result = jpushClient.sendPush(payload);\n    LOG.info(\"Got result - \" + result);\n    Thread.sleep(5000);\n    // 请求结束后，调用 NettyHttpClient 中的 close 方法，否则进程不会退出。\n    jpushClient.close();\n} catch(InterruptedException e) {\n    e.printStackTrace();\n}\n```\n\n3.2.17 版本后，在 PushClient 中添加了 setHttpClient(IHttpClient client) 方法，用户可以自由切换 ApacheHttpClient，NettyHttpClient 或是 NativeHttpClient。\n\n### 推送样例\n\n\u003e 以下片断来自项目代码里的文件：example / cn.jpush.api.examples.PushExample\n\n```Java\n    JPushClient jpushClient = new JPushClient(MASTER_SECRET, APP_KEY, null, ClientConfig.getInstance());\n\n    // For push, all you need do is to build PushPayload object.\n    PushPayload payload = buildPushObject_all_all_alert();\n\n    try {\n        PushResult result = jpushClient.sendPush(payload);\n        LOG.info(\"Got result - \" + result);\n\t\n    } catch (APIConnectionException e) {\n        // Connection error, should retry later\n        LOG.error(\"Connection error, should retry later\", e);\n\n    } catch (APIRequestException e) {\n        // Should review the error, and fix the request\n        LOG.error(\"Should review the error, and fix the request\", e);\n        LOG.info(\"HTTP Status: \" + e.getStatus());\n        LOG.info(\"Error Code: \" + e.getErrorCode());\n        LOG.info(\"Error Message: \" + e.getErrorMessage());\n    }\n```\n\n进行推送的关键在于构建一个 PushPayload 对象。以下示例一般的构建对象的用法。\n\n* 快捷地构建推送对象：所有平台，所有设备，内容为 ALERT 的通知。\n\n```Java\n\tpublic static PushPayload buildPushObject_all_all_alert() {\n\t    return PushPayload.alertAll(ALERT);\n\t}\n```\n\n* 构建推送对象：所有平台，推送目标是别名为 \"alias1\"，通知内容为 ALERT。\n\n```Java\n    public static PushPayload buildPushObject_all_alias_alert() {\n        return PushPayload.newBuilder()\n                .setPlatform(Platform.all())\n                .setAudience(Audience.alias(\"alias1\"))\n                .setNotification(Notification.alert(ALERT))\n                .build();\n    }\n```\n\n* 构建推送对象：平台是 Android，目标是 tag 为 \"tag1\" 的设备，内容是 Android 通知 ALERT，并且标题为 TITLE。\n\n```Java\n    public static PushPayload buildPushObject_android_tag_alertWithTitle() {\n        return PushPayload.newBuilder()\n                .setPlatform(Platform.android())\n                .setAudience(Audience.tag(\"tag1\"))\n                .setNotification(Notification.android(ALERT, TITLE, null))\n                .build();\n    }\n```\n\n* 构建推送对象：平台是 iOS，推送目标是 \"tag1\", \"tag_all\" 的交集，推送内容同时包括通知与消息 - 通知信息是 ALERT，角标数字为 5，通知声音为 \"happy\"，并且附加字段 from = \"JPush\"；消息内容是 MSG_CONTENT。通知是 APNs 推送通道的，消息是 JPush 应用内消息通道的。APNs 的推送环境是“生产”（如果不显式设置的话，Library 会默认指定为开发）\n\n```Java\n    public static PushPayload buildPushObject_ios_tagAnd_alertWithExtrasAndMessage() {\n        return PushPayload.newBuilder()\n                .setPlatform(Platform.ios())\n                .setAudience(Audience.tag_and(\"tag1\", \"tag_all\"))\n                .setNotification(Notification.newBuilder()\n                        .addPlatformNotification(IosNotification.newBuilder()\n                                .setAlert(ALERT)\n                                .setBadge(5)\n                                .setSound(\"happy\")\n                                .addExtra(\"from\", \"JPush\")\n                                .build())\n                        .build())\n                 .setMessage(Message.content(MSG_CONTENT))\n                 .setOptions(Options.newBuilder()\n                         .setApnsProduction(true)\n                         .build())\n                 .build();\n    }\n```\n\n* 构建推送对象：平台是 Andorid 与 iOS，推送目标是 （\"tag1\" 与 \"tag2\" 的并集）交（\"alias1\" 与 \"alias2\" 的并集），推送内容是 - 内容为 MSG_CONTENT 的消息，并且附加字段 from = JPush。\n\n```Java\n    public static PushPayload buildPushObject_ios_audienceMore_messageWithExtras() {\n        return PushPayload.newBuilder()\n                .setPlatform(Platform.android_ios())\n                .setAudience(Audience.newBuilder()\n                        .addAudienceTarget(AudienceTarget.tag(\"tag1\", \"tag2\"))\n                        .addAudienceTarget(AudienceTarget.alias(\"alias1\", \"alias2\"))\n                        .build())\n                .setMessage(Message.newBuilder()\n                        .setMsgContent(MSG_CONTENT)\n                        .addExtra(\"from\", \"JPush\")\n                        .build())\n                .build();\n    }\n```\n\n* 构建推送对象：推送内容包含SMS信息\n\n```Java\n    public static void testSendWithSMS() {\n        JPushClient jpushClient = new JPushClient(masterSecret, appKey);\n        try {\n            SMS sms = SMS.newBuilder()\n            \t\t.setDelayTime(1000)\n            \t\t.setTempID(2000)\n            \t\t.addPara(\"Test\", 1)\n            \t\t.build();\n            PushResult result = jpushClient.sendAndroidMessageWithAlias(\"Test SMS\", \"test sms\", sms, \"alias1\");\n            LOG.info(\"Got result - \" + result);\n        } catch (APIConnectionException e) {\n            LOG.error(\"Connection error. Should retry later. \", e);\n        } catch (APIRequestException e) {\n            LOG.error(\"Error response from JPush server. Should review and fix it. \", e);\n            LOG.info(\"HTTP Status: \" + e.getStatus());\n            LOG.info(\"Error Code: \" + e.getErrorCode());\n            LOG.info(\"Error Message: \" + e.getErrorMessage());\n        }\n    }\n```\n\n### 统计获取样例\n\n\u003e 以下片断来自项目代码里的文件：example / cn.jpush.api.examples.ReportsExample\n\n```Java\n    JPushClient jpushClient = new JPushClient(masterSecret, appKey);\n    try {\n        ReceivedsResult result = jpushClient.getReportReceiveds(\"1942377665\");\n        LOG.debug(\"Got result - \" + result);\n\n    } catch (APIConnectionException e) {\n        // Connection error, should retry later\n        LOG.error(\"Connection error, should retry later\", e);\n\n    } catch (APIRequestException e) {\n        // Should review the error, and fix the request\n        LOG.error(\"Should review the error, and fix the request\", e);\n        LOG.info(\"HTTP Status: \" + e.getStatus());\n        LOG.info(\"Error Code: \" + e.getErrorCode());\n        LOG.info(\"Error Message: \" + e.getErrorMessage());\n    }\n```\n\n### Tag/Alias 样例\n\n\u003e 以下片断来自项目代码里的文件：example / cn.jpush.api.examples.DeviceExample\n\n* 获取Tag Alias\n```Java\n    try {\n        TagAliasResult result = jpushClient.getDeviceTagAlias(REGISTRATION_ID1);\n\n        LOG.info(result.alias);\n        LOG.info(result.tags.toString());\n    } catch (APIConnectionException e) {\n        LOG.error(\"Connection error. Should retry later. \", e);\n    } catch (APIRequestException e) {\n        LOG.error(\"Error response from JPush server. Should review and fix it. \", e);\n        LOG.info(\"HTTP Status: \" + e.getStatus());\n        LOG.info(\"Error Code: \" + e.getErrorCode());\n        LOG.info(\"Error Message: \" + e.getErrorMessage());\n    }\n```\n\n* 绑定手机号\n\n```Java\n    try {\n        DefaultResult result =  jpushClient.bindMobile(REGISTRATION_ID1, \"13000000000\");\n        LOG.info(\"Got result \" + result);\n    } catch (APIConnectionException e) {\n        LOG.error(\"Connection error. Should retry later. \", e);\n    } catch (APIRequestException e) {\n        LOG.error(\"Error response from JPush server. Should review and fix it. \", e);\n        LOG.info(\"HTTP Status: \" + e.getStatus());\n        LOG.info(\"Error Code: \" + e.getErrorCode());\n        LOG.info(\"Error Message: \" + e.getErrorMessage());\n    }\n```\n\n### Schedule 样例\n\n\u003e 以下片断来自项目代码里的文件：example / cn.jpush.api.examples.ScheduleExample\n\n```Java\n    JPushClient jpushClient = new JPushClient(masterSecret, appKey);\n    String name = \"test_schedule_example\";\n    String time = \"2016-07-30 12:30:25\";\n    PushPayload push = PushPayload.alertAll(\"test schedule example.\");\n    try {\n        ScheduleResult result = jpushClient.createSingleSchedule(name, time, push);\n        LOG.info(\"schedule result is \" + result);\n    } catch (APIConnectionException e) {\n        LOG.error(\"Connection error. Should retry later. \", e);\n    } catch (APIRequestException e) {\n        LOG.error(\"Error response from JPush server. Should review and fix it. \", e);\n        LOG.info(\"HTTP Status: \" + e.getStatus());\n        LOG.info(\"Error Code: \" + e.getErrorCode());\n        LOG.info(\"Error Message: \" + e.getErrorMessage());\n    }\n```\n\n### Custom Client 样例\n\n\u003e 以下片断来自项目代码里面的文件：example / cn.jpush.api.examples.ClientExample\n\n* 配置的SSLVersion表示指定至少支持的协议版本，也可能支持其他多个协议版本，最终支持的协议版本列表取决于JRE和运行环境\n```Java\n    public static void testCustomClient() {\n\t\tClientConfig config = ClientConfig.getInstance();\n        config.setMaxRetryTimes(5);\n        config.setConnectionTimeout(10 * 1000);\t// 10 seconds\n        config.setSSLVersion(\"TLSv1.1\");\t\t// JPush server supports SSLv3, TLSv1, TLSv1.1, TLSv1.2\n\n        JPushClient jPushClient = new JPushClient(masterSecret, appKey, null, config);\n\t}\n\n    public static void testCustomPushClient() {\n        ClientConfig config = ClientConfig.getInstance();\n        config.setApnsProduction(false); \t// development env\n        config.setTimeToLive(60 * 60 * 24); // one day\n\n    //\tconfig.setGlobalPushSetting(false, 60 * 60 * 24); // development env, one day\n\n        JPushClient jPushClient = new JPushClient(masterSecret, appKey, null, config); \t// JPush client\n\n    //\tPushClient pushClient = new PushClient(masterSecret, appKey, null, config); \t// push client only\n\n    }\n```\n\n### Image Client 样例\n\n\u003e 以下片断来自项目代码里面的文件：example / cn.jpush.api.examples.ImageExample\n* 支持通过URL或者文件来上传图片\n```Java\n    public static void testUploadImageByUrl() throws APIConnectionException, APIRequestException {\n        ImageClient client = new ImageClient(MASTER_SECRET, APP_KEY);\n        ImageUrlPayload payload = ImageUrlPayload.newBuilder()\n        .setImageType(ImageType.LARGE_ICON)\n        .setImageUrl(\"http://xxx.com/image/a.jpg\")\n        .build();\n        ImageUploadResult imageUploadResult = client.uploadImage(payload);\n        String mediaId = imageUploadResult.getMediaId();\n    }\n\n    public static void testUploadImageByFile() {\n        ImageClient client = new ImageClient(MASTER_SECRET, APP_KEY);\n        ImageFilePayload payload = ImageFilePayload.newBuilder()\n        .setImageType(ImageType.BIG_PICTURE)\n        // 本地文件路径\n        .setOppoFileName(\"/MyDir/a.jpg\")\n        .setXiaomiFileName(\"/MyDir/a.jpg\")\n        .build();\n        ImageUploadResult imageUploadResult = client.uploadImage(payload);\n        String mediaId = imageUploadResult.getMediaId();\n    }\n```\n\n### Weblogic 使用Java SDK\n\nWeblogic在使用jpush-api-java-client时需要注意的一些事项。\n\n#### 注意事项\n\n本文档基于weblogic 10.3.6 版本，12版本请自己对应配置路径。\n\n极个别时候，证书会有版本升级等情况，所以一定要验证当前使用的证书和官方证书的指纹是否一致。\n\n**Weblogic console 设置**\n\n+ 【主机名验证】设置为无，否则默认使用weblogic.security.SSL.HostnameVerifier进行主机名验证，导致Hostname验证失败\n    + 配置路径 Weblogic Console \u003e 服务器设置 \u003e SSL \u003e 高级 \u003e 主机名验证\n+ 选择【使用 JSSE SSL】，因为Weblogic默认的加密算法和Java标准的加密算法不一样\n    + 配置路径 Weblogic Console \u003e 服务器设置 \u003e SSL \u003e 高级 \u003e 使用 JSSE SSL\n\n**证书配置**\n\n+ 检查Weblogic使用的信任密钥库的位置\n    + 默认使用的文件是 JRE目录下面的  jre\\lib\\security\\cacerts 文件\n    + 有些开发者可能会改为自定义的信任密钥库\n+ 检查对应的信任库是否包含了Geo Trust的根证书或者Geo Trust SSL二级 证书\n    + 举例：keytool -list -keystore cacerts\n    + 此过程需要信任库的密码（默认changeit）\n    + 如果包含这两个证书中任意一个，调用JPush接口都可以调用通过\n+ 如果信任库不包含上述证书，需要导入公钥到对应的信任库\n    + 打开jpush.cn，导出公钥（可以是Geo Trust根证书、Geo Trust SSL 或者 *.jpush.cn 三个任意一个，具体导出方法请百度）\n    + 将导出的公钥证书导入到步骤1对应的信任库\n    + 举例：keytool -import -alias geotrustssl -keystore cacerts -file GeoTrustSSL.cer\n    + 此过程需要信任库的密码（默认changeit）\n\n**证书对比方式**\n\n+ 执行 keytool -list -keystore mykey.jks  命令列出信任库里的所有公钥，观察对应证书的指纹\n+ 检查官网证书，观察对应证书的指纹\n+ 比较两个指纹是否一致，如下图所示\n![jpush_weblogic](https://docs.jiguang.cn/jpush/server/3rd/image/weblogic.png)\n","funding_links":[],"categories":["Java"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpush%2Fjpush-api-java-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpush%2Fjpush-api-java-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpush%2Fjpush-api-java-client/lists"}