ApiBoot 文档

ApiBoot 集成极光App消息推送

消息推送是接口服务项目内不可或缺的一部分,用于向用户发送操作消息提醒、广告等。

ApiBoot内提供了消息推送的支持,目前集成的第三方组件为极光推送ApiBoot遵循开箱即用的原则,所以在集成推送时仍然只需要简单的必要配置即可完成集成。

添加依赖

pom.xml配置文件添加依赖如下所示:

//...
  <!--ApiBoot Message Push Starter-->
  <dependency>
    <groupId>org.minbox.framework</groupId>
    <artifactId>api-boot-starter-message-push</artifactId>
  </dependency>
//...

注意:如果未添加ApiBoot版本依赖,请访问版本依赖查看添加方式。

相关配置

配置名称 默认值 描述
api.boot.push.production true 配置IOS平台的推送环境,true:生产环境(AppStore下载的APP)
api.boot.push.client.master-secret 单客户端推送配置masterSecret
api.boot.push.client.app-key 单客户端推送配置appKey
api.boot.push.multiple.xxx.master-secret 多客户端推送配置masterSecret
api.boot.push.multiple.xxx.app-key 多客户端推送配置appKey

在上面multiple相关的配置内部是key->value结构配置,其中"xxx"用于配置@MessagePushSwitch("xxx")的value值

单环境推送

如果你的接口服务项目只集成推送到一个APP客户端,那么可以采用单环境推送的模式,该环境使用api.boot.push.client前缀的配置进行配置极光推送的两个秘钥,如下所示:

# ApiBoot Config
api:
  boot:
    push:
      # 推送默认配置
      client:
        # 秘钥
        master-secret: xxx
        # appKey
        app-key: xxx

配置完成后我们就可以通过注入ApiBootMessagePushService接口来进行发送推送业务,如下所示:

/**
 * ApiBoot Message Push Service
 */
@Autowired
private ApiBootMessagePushService apiBootMessagePushService;

/**
  * 安卓推送示例
  * @see org.minbox.framework.api.boot.plugin.message.push.model.PushClientConfig
  */
public void test() {
  apiBootMessagePushService.executePush(
    MessagePushBody.builder()
    // 推送安卓平台
    // 如需更换推送平台,可以查看PusherPlatform枚举定义
    .platform(PusherPlatform.ANDROID)
    // 标题
    .title("消息推送")
    // 内容
    .message("测试消息推送内容")
    // 接收人的别名(App端开发人员进行设置)
    .alias(Arrays.asList("xxxx"))
    .build()
  );
}

ApiBoot Message Push如不配置使用@MessagePushSwithc注解时,使用默认的配置,也就是api.boot.push.client开头的相关配置信息。

多环境推送

在一个接口服务系统内,可能存在向多个APP客户端进行推送消息,那么这种情况ApiBoot Message Push也做了支持,内部通过AOP的方法切面进行处理。

多环境下的配置要做修改,如下所示:

# ApiBoot Config
api:
  boot:
    push:
      multiple:
        # user app 推送配置
        user:
          master-secret: xxx
          app-key: xxxx
        # other app 推送配置
        other:
          master-secret: xxxxxx
          app-key: xxxxxx

在上面我们配置了两个APP客户端的推送信息,名称分别为userother,这个名称对应@MessagePushSwitch注解的value值使用。

在上面配置了userother两个客户端,使用具体的环境我们只需要在调用方法上添加@MessagePushSwitch注解,如下所示:

// other app 推送
@MessagePushSwitch("other")
public void testOther() {
  //....
}

// user app 推送
@MessagePushSwitch("user")
public void testUser() {
  //....
}

指定别名推送

在推送消息时,ApiBoot提供了多种方式,其中可以根据alias别名进行推送,alias是由App前端开发人员在集成SDK时设置的值,这时就需要接口开发人员与APP开发人员的约定来完成推送逻辑,一般可以使用用户的编号来作为别名,根据别名推送如下所示:

// 别名推送示例
public void test() {
  apiBootMessagePushService.executePush(
    MessagePushBody.builder()
    .platform(PusherPlatform.ANDROID)
    .title("消息推送")
    .message("测试消息推送内容")
    // 配置别名,别名可配置多个
    .alias(Arrays.asList("xxxx"))
    .build()
  );
}

指定分组推送

分组推送跟别名推送几乎一致,也是APP开发人员在调用SDK时对具体的用户划分的一个分组群体,向分组进行推送消息时,分组内的所有用户都可以收到。

如下所示:

// 分组推送示例
public void test() {
  apiBootMessagePushService.executePush(
    MessagePushBody.builder()
    .platform(PusherPlatform.ANDROID)
    .title("消息推送")
    .message("测试消息推送内容")
    // 推送group1内的所有用户
    // 注意:分组优先级低于别名
    .tags(Arrays.asList("group1"))
    .build()
  );
}

如果同时配置别名、分组两种推送方式,则会使用别名

携带自定义参数推送

ApiBoot Message Push可以给APP端推送的消息携带自定义的扩展参数,让APP端做一些特殊的处理,携带扩展参数如下所示:

// 自定义参数示例
public void test() {
  apiBootMessagePushService.executePush(
    MessagePushBody.builder()
    .platform(PusherPlatform.ANDROID)
    .title("消息推送")
    .message("测试消息推送内容")
    .alias(Arrays.asList("xxxx"))
    // 扩展参数
    .extras(new HashMap(1) {
      {
        put("role", "USER");
      }
    })
    .build()
  );
}

自定义推送提示声音

ApiBoot Message Push可以推送自定义提示的声音,当然也需要APP开发人员做配置才可以,如下所示:

public void test() {
  apiBootMessagePushService.executePush(
    MessagePushBody.builder()
    .platform(PusherPlatform.ANDROID)
    .title("消息推送")
    .message("测试消息推送内容")
    .alias(Arrays.asList("xxxx"))
    // 手机系统默认提示音
    .sound("default")
    .build()
  );
}

sound方法可以设置与APP开发人员约定的声明唯一名称。

设置推送角标数值

推送消息时APP的角标数值是可以自定义的,当然我们一般都是叠加,如下所示:

public void test() {
  apiBootMessagePushService.executePush(
    MessagePushBody.builder()
    .platform(PusherPlatform.ANDROID)
    .title("消息推送")
    .message("测试消息推送内容")
    .alias(Arrays.asList("xxxx"))
    .tags(Arrays.asList("group1"))
    // 角标数值,默认为+1
    .badge(999)
    .build()
  );
}