推送API

推送API

简述

个推为开发者提供了如下4种消息推送方式:

  • toSingle :简称“单推”,指向单个用户推送消息
  • toList:简称“批量推”,指向制定的一批用户推送消息
  • toApp:简称“群推”,指向APP符合筛选条件的所有用户推送消息,支持定速推送、定时推送,支持条件的交并补功能
  • toGroup:个推针对直播间提供定制化解决方案,解决直播间海量消息传输。点击查看详细说明

【toSingle】执行单推

功能描述

向单个用户发送消息,可根据cid或别名指定用户。

注:个推使用clientid来标识每个独立的用户,每一台终端上每一个app拥有一个独立的clientid。

接口名称

IGeTui.pushMessageToSingle(message, target)

请求参数

名称 类型 是否必需 默认值 描述
message IGtSingleMessage 消息体
target Target 推送目标

SingleMessage

名称 类型 是否必需 默认值 描述
isOffline bool false 是否保持离线消息
offlineExpireTime long 1小时 过多久该消息离线失效(单位毫秒) 支持1-72小时*3600000毫秒
pushNetWorkType long 0 推送网络要求
0:联网方式不限;
1:仅wifi;
2:仅移动网络
data ITemplate 设置推送效果(模版),点击查看详细说明

Target

名称 类型 是否必需 默认值 描述
appId String 应用唯一ID
clientId String 客户端身份ID
clientId和alias二选一
alias String 用户别名
clientId和alias二选一

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
taskId String 任务ID
status String 推送结果
successed_offline 离线下发
successed_online 在线下发
successed_ignore 最近90天内不活跃用户不下发

返回示例

{
    "result":"ok",
    "taskId":"xxx",
    "status":"successed_online"
}

代码示例

import RequestException
from igetui.igt_target import Target
from igetui.template.igt_notification_template import NotificationTemplate
from igetui.template.style.Style0 import Style0
from igt_push import IGeTui, IGtSingleMessage

# 详见【概述】-【服务端接入步骤】-【STEP1】说明,获得的应用配置

APPID = ""
APPKEY = ""
MASTERSECRET = ""
CID = ""
# 也可以使用别名推送方式
# ALIAS = ""
HOST = "http://api.getui.com/apiex.htm"


def pushMessageToSingle():
    push = IGeTui(HOST, APPKEY, MASTERSECRET)
    template = NotificationTemplateDemo()
    message = IGtSingleMessage()
    # 是否离线推送
    message.isOffline = True
    # 离线有效时间
    message.offlineExpireTime = 1000 * 3600 * 12
    message.data = template
    # 可选,推送的网络类型:(0:不限;1:wifi;2:4G/3G/2G)
    message.pushNetWorkType = 0
    target = Target()
    target.appId = APPID
    target.clientId = CID
    # 也可以使用别名推送方式
    # target.clientId = ALIAS
    try:
        ret = push.pushMessageToSingle(message, target)
        print(ret)
    except RequestException as e:
        requstId = e.getRequestId()
        ret = push.pushMessageToSingle(message, target, requstId)
        print(ret)


# 通知透传模板动作内容
def NotificationTemplateDemo():
    template = NotificationTemplate()
    # 设置APPID与APPKEY
    template.appId = APPID
    template.appKey = APPKEY

    style = Style0()
    # 设置通知栏标题与内容
    style.title = str("请填入通知标题")
    style.text = str("请填入通知内容")
    # 配置通知栏图标
    style.logo = ""
    # 配置通知栏网络图标
    style.logoUrl = ""
    # 设置通知是否响铃,震动,或者可清除
    style.isRing = True
    style.isVibrate = True
    style.isClearable = True
    style.channel = "通知渠道ID"
    style.channelName = "通知渠道名称"
    style.channelLevel = 3  # 设置通知渠道优先级

    template.style = style
    template.transmissionType = 1  # 透传消息接受方式设置,1:立即启动APP,2:客户端收到消息后需要自行处理
    template.transmissionContent = "请输入您要透传的内容"
    return template


pushMessageToSingle()

【toSingle】执行批量单推

功能说明

合并多个单推任务,统一提交,可提升推送效率。

接口说明

BatchImpl.submit();

调用步骤

STEP1:调用push.getBatch() 获取操作对象

STEP2:调用batch.add() 添加单推任务

STEP3:调用batch.submit() 提交任务

请求参数

推送参数message和target与对单个用户推送消息使用的的参数相同

注:此接口不支持别名(alias)参数

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
info JsonObject 每个cid推送的结果

返回示例

{
    "result":"ok",
    "info":{
        "1":{
            "result":"ok",
            "taskId":"OSS-xxx",
            "cid":"xxx",
            "status":"successed_online"
        },
        "2":{
            "result":"ok",
            "taskId":"OSS-xxx",
            "cid":"xxx",
            "status":"successed_offline"
        }
    }
}

代码示例

from igetui.igt_target import Target
from igetui.template.igt_link_template import LinkTemplate
from igetui.template.igt_transmission_template import TransmissionTemplate
from igetui.template.style.Style0 import Style0
from igt_push import IGeTui, IGtSingleMessage, BatchImpl

# 详见【概述】-【服务端接入步骤】-【STEP1】说明,获得的应用配置
APPID = ""
APPKEY = ""
MASTERSECRET = ""

CID_A = ""
CID_B = ""

HOST = "http://api.getui.com/apiex.htm"


def pushMessageToSingleBatch():
    push = IGeTui(HOST, APPKEY, MASTERSECRET)
    batch = BatchImpl(APPKEY, push)

    try:
        # 构建客户a的透传消息a
        constructClientTransMsg(CID_A, "msg_A", batch)
        # 构建客户B的点击通知打开网页消息b
        constructClientLinkMsg(CID_B, "msg_B", batch)
        ret = batch.submit()
        print(ret)
    except Exception as e:
        ret = batch.retry()
        print(ret)


def constructClientTransMsg(cid, msg, batch):
    message = IGtSingleMessage()
    template = TransmissionTemplate()
    # 设置APPID与APPKEY
    template.appId = APPID
    template.appKey = APPKEY
    template.transmissionContent = msg
    template.transmissionType = 2  # 透传消息接受方式设置,1:立即启动APP,2:客户端收到消息后需要自行处理

    message.data = template
    message.isOffline = True
    message.offlineExpireTime = 360 * 1000

    # 设置推送目标,填入appid和clientId
    target = Target()
    target.appId = APPID
    target.clientId = cid
    batch.add(message, target)


def constructClientLinkMsg(cid, msg, batch):
    message = IGtSingleMessage()
    template = LinkTemplate()
    # 设置APPID与APPKEY
    template.appId = APPID
    template.appKey = APPKEY

    style = Style0()
    # 设置通知栏标题与内容
    style.title = "请输入通知栏标题"
    style.text = msg
    # 配置通知栏图标
    style.logo = "icon.png"
    # 配置通知栏网络图标
    style.logoUrl = ""
    # 设置通知是否响铃,震动,或者可清除
    style.isRing = True
    style.isVibrate = True
    style.isClearable = True

    template.style = style

    message.data = template
    message.isOffline = True
    message.offlineExpireTime = 360 * 1000

    # 设置推送目标,填入appid和clientId
    target = Target()
    target.appId = APPID
    target.clientId = cid
    batch.add(message, target)


pushMessageToSingleBatch()

【toList】获取taskId

功能说明

toList推送指向指定的用户列表进行推送。此接口用户创建消息公共体,为toList推送前置步骤

操作步骤如下:

STEP1:创建消息公共体,获取taskId。

STEP2:调用【toList】执行推送接口执行下发
说明:taskId等价于contentId

对应接口

IGeTui.getContentId(message, taskGroupName = None)

限制说明

注:此接口频次限制200万次/天,申请修改请联系邮箱:lieg@getui.com

请求参数

名称 类型 是否必需 默认值 描述
message IGtListMessage 消息体
taskGroupName string 任务组名
多个消息公共体可以用同一个任务组名,后续可根据任务组名查询推送情况

IGtListMessage

名称 类型 是否必需 默认值 描述
isOffline bool false 是否保持离线消息
offlineExpireTime long 1小时 过多久该消息离线失效(单位毫秒) 支持1-72小时*3600000毫秒
pushNetWorkType long 0 推送网络要求
0:联网方式不限;
1:仅wifi;
2:仅移动网络
data ITemplate 设置推送效果(模版),点击查看详细说明

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
contentId String 就是taskId,任务ID(格式OSL-yyMM_XXXXXX),用于批量推,此id可以多次使用,有效期为用户设置的离线时间

返回示例

{
    "result":"ok",
    "contentId":"xxx"
}

【toList】执行批量推

功能说明

上传clientid或别名列表,对列表中所有clientid或别名用户进行消息推送。调用此接口前需调用获取taskId接口设置消息内容。

对应接口

IGeTui.pushMessageToList(contentId, targetList)

限制说明

注:单次推送数量限制1000以内,此接口频次限制200万次/天,申请修改请联系邮箱:lieg@getui.com

请求参数

名称 类型 是否必需 默认值 描述
contentId String 就是taskId,任务ID,是获取taskId接口返回值
相同taskId可以多次使用
targetList List<Target> 推送目标列表,单次推送数量限制1000以内

Target

名称 类型 是否必需 默认值 描述
appId String 应用唯一ID
clientId String 客户端身份ID
clientId和alias至少选其一
alias String 用户别名
clientId和alias至少选其一

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
contentId String 就是taskId,任务ID
details JsonObject 环境变量设置gexin_pushList_needDetails为true时返回此数据,不设置或为false不返还此数据。
aliasDetails JsonObject 环境变量设置gexin_pushList_needAliasDetails为true时返回此数据,不设置或为false不返还此数据。

返回示例

{
    "result":"ok",
    "contentId":"",
    "details":{
            "cid1":"successed_online",
            "cid2":"successed_offline",
            "cid3":"successed_ignore"
     },
     "aliasDetails":{
            "cid1":"successed_online",
            "cid2":"successed_offline",
            "cid3":"successed_ignore"
     }
}

代码示例

import os

from igetui.igt_target import Target
from igetui.template.igt_notification_template import NotificationTemplate
from igetui.template.style.Style0 import Style0
from igt_push import IGeTui, IGtListMessage

# 详见【概述】-【服务端接入步骤】-【STEP1】说明,获得的应用配置
APPID = ""
APPKEY = ""
MASTERSECRET = ""

CID_1 = ""
CID_2 = ""
# 别名推送方式
# ALIAS_1 = ""
# ALIAS_2 = ""

HOST = "http://api.getui.com/apiex.htm"


def pushMessageToList():
    # 配置返回每个用户返回用户状态,可选
    os.environ['gexin_pushList_needDetails'] = 'true'

    push = IGeTui(HOST, APPKEY, MASTERSECRET)
    # 通知透传模板
    template = NotificationTemplateDemo()
    message = IGtListMessage()

    message.data = template
    # 设置消息离线,并设置离线时间
    message.isOffline = True
    # 离线有效时间,单位为毫秒
    message.offlineExpireTime = 24 * 1000 * 3600
    # 配置推送目标
    targets = []
    target1 = Target()
    target2 = Target()
    target1.appId = APPID
    target1.clientId = CID_1
    # target1.alias = ALIAS_1
    target2.appId = APPID
    target2.clientId = CID_2
    # target2.alias = ALIAS_2
    targets.append(target1)
    targets.append(target2)
    # taskId用于在推送时去查找对应的message
    taskId = push.getContentId(message)
    ret = push.pushMessageToList(taskId, targets)
    print(ret)


def NotificationTemplateDemo():
    template = NotificationTemplate()
    # 设置APPID与APPKEY
    template.appId = APPID
    template.appKey = APPKEY

    style = Style0()
    # 设置通知栏标题与内容
    style.title = "请填入通知标题"
    style.text = "请填入通知内容"
    # 配置通知栏图标
    style.logo = ""
    # 配置通知栏网络图标
    style.logoUrl = ""
    # 设置通知是否响铃,震动,或者可清除
    style.isRing = True
    style.isVibrate = True
    style.isClearable = True
    style.channel = "通知渠道ID"
    style.channelName = "通知渠道名称"
    style.channelLevel = 3  # 设置通知渠道优先级

    template.style = style
    template.transmissionType = 1  # 透传消息接受方式设置,1:立即启动APP,2:客户端收到消息后需要自行处理
    template.transmissionContent = "请输入您要透传的内容"
    return template


pushMessageToList()

【toList】停止批量推

功能说明

对于客户端在线还没有下发或者离线还没收到的通知,停止下发。

对应接口

IGeTui.stop(contentId)

请求参数

名称 类型 是否必需 默认值 描述
contentId String 就是taskId,任务ID(格式OSL-yyMM_XXXXXX)

返回参数

名称 类型 描述
- bool true:成功;
false:失败

【toApp】执行群推

功能说明

对指定应用的所有(或符合筛选条件的)用户群发推送消息。有定时、定速功能。

对应接口

IGeTui.pushMessageToApp(message,taskGroupName = None)

限制说明

注:此接口频次限制100次/天,每分钟不能超过5次,定时推送功能需要申请开通才可以使用,申请修改请联系邮箱:lieg@getui.com

  • 使用推送的sdk包版本必须大于等于4.0.1.17。
  • 设定推送的时间格式为yyyyMMddHHmm 例如:201908081900,任务将会在2019年08月08日19点00分推送。
  • 对时间的设定有一定的要求:
    1. 时间格式不正确 提交任务时 将直接返回失败。
    2. 下发时间小于当前时间 提交任务时将直接返回失败。
    3. 下发时间超过系统所允许的最大时间点 提交任务 将直接返回失败

请求参数

名称 类型 是否必需 默认值 描述
message IGtAppMessage 消息体
taskGroupName String 任务别名

IGtAppMessage

名称 类型 是否必需 默认值 描述
isOffline bool false 是否保持离线消息
offlineExpireTime long 1小时 过多久该消息离线失效(单位毫秒) 支持1-72小时*3600000毫秒
pushNetWorkType long 0 推送网络要求
0:联网方式不限;
1:仅wifi;
2:仅移动网络
data ITemplate 设置推送效果,点击查看详细说明
appIdList List<String> appId列表,只有第一个有效
conditions AppConditions 筛选条件交并补功能
speed int 定速推送
例如100,个推控制下发速度在100条/秒左右
pushTime String 定时推送
格式要求为yyyyMMddHHmm
需要申请开通套餐

AppConditions

// AppConditions类的实例方法
AppConditions.addCondition(String key, List<String> values, int optType);
名称 类型 是否必需 默认值 描述
key String 查询条件键(phoneType 手机类型,region 省市,tag 用户标签),其他key可开通VIP套餐,通过查询用户画像接口获取
values List 查询条件值列表,其中
手机型号使用如下参数ANDROIDIOS,需要大写;
省市使用编号,点击下载文件region_code.data
optType String 0 条件类型(OptType.OR 或, OptType.AND 与, OptType.NOT 非)
  • 需要发送给城市在A,B,C里面,没有设置tagtest标签,手机型号为ANDROID的用户,用条件交并补功能可以实现,city(A|B|C) && !tag(tagtest) && phonetype(ANDROID)

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
contentId String 任务ID

返回示例

{
    "result":"ok",
    "contentId":"xxx"
}

代码示例

from igetui.template.igt_notification_template import NotificationTemplate
from igetui.template.style.Style0 import Style0
from igt_push import IGeTui, IGtAppMessage, AppConditions, OptType

# 详见【概述】-【服务端接入步骤】-【STEP1】说明,获得的应用配置
APPID = ""
APPKEY = ""
MASTERSECRET = ""

HOST = "http://api.getui.com/apiex.htm"


def pushMessageToApp():
    push = IGeTui(HOST, APPKEY, MASTERSECRET)
    # 通知透传模板
    template = NotificationTemplateDemo()
    message = IGtAppMessage()
    message.data = template
    # 设置消息离线,并设置离线时间
    message.isOffline = True
    # 离线有效时间,单位为毫秒
    message.offlineExpireTime = 24 * 1000 * 3600
    cdt = AppConditions()
    appIdList = [APPID]
    message.appIdList = appIdList
    # 手机类型
    phoneTypeList = ["IOS", "ANDROID"]
    # 省份
    provinceList = ["33010000", "51010000"]  # 参见region_code.data
    # 自定义tag
    tagList = ["tag001"]
    # 查询可推送的用户画像(需要开通VIP套餐)
    personaTagResult = push.getPersonaTags(APPID)
    print(personaTagResult)
    # 工作
    jobs = ["0102", "0110"]
    # 年龄
    age = ["0000"]

    cdt.addCondition(AppConditions.PHONE_TYPE, phoneTypeList, OptType.OR)
    cdt.addCondition(AppConditions.REGION, provinceList, OptType.OR)
    cdt.addCondition(AppConditions.TAG, tagList, OptType.AND)
    cdt.addCondition("jobs", jobs, OptType.NOT)
    cdt.addCondition("age", age)
    message.conditions = cdt

    ret = push.pushMessageToApp(message, "任务别名_toApp")
    print(ret)


def NotificationTemplateDemo():
    template = NotificationTemplate()
    # 设置APPID与APPKEY
    template.appId = APPID
    template.appKey = APPKEY

    style = Style0()
    # 设置通知栏标题与内容
    style.title = "请填入通知标题"
    style.text = "请填入通知内容"
    # 配置通知栏图标
    style.logo = ""
    # 配置通知栏网络图标
    style.logoUrl = ""
    # 设置通知是否响铃,震动,或者可清除
    style.isRing = True
    style.isVibrate = True
    style.isClearable = True
    style.channel = "通知渠道ID"
    style.channelName = "通知渠道名称"
    style.channelLevel = 3  # 设置通知渠道优先级

    template.style = style
    template.transmissionType = 1  # 透传消息接受方式设置,1:立即启动APP,2:客户端收到消息后需要自行处理
    template.transmissionContent = "请输入您要透传的内容"
    return template


pushMessageToApp()

【任务】停止任务

功能说明

对正处于推送状态,或者未接收的消息停止下发

对应接口

IGeTui.stop(contentId)

返回参数

名称 类型 描述
- bool true:成功;
false:失败

请求参数

名称 类型 是否必需 默认值 描述
contentId string 就是taskId,任务ID(格式OSL-yyMM_XXXXXX)

【任务】查询定时任务

功能说明

此接口可根据taskID查询所有定时任务

对应接口

IGeTui.getScheduleTask(taskId, appId);

请求参数

名称 类型 是否必需 默认值 描述
taskId String 任务ID
appId String 应用唯一ID

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
taskId String 任务ID
taskDetail JsonObject 任务详情

taskDetail

名称 类型 描述
desc String 查询结果描述
status String 查询结果code码
pushContent String 推送内容
pushTime String 推送任务设置的定时时间
creatTime String 创建任务时间
sendResult String 任务状态,有如下值
HAS_DELETE:定时任务已经被删除
SEND_SUCCESS:定时任务发送成功
DO_NOT_SEND:定时任务还没有发送
SEND_FAILED:定时任务发送失败

返回示例

{
    "result":"ok",
    "taskId":"xxx",
      "taskDetail": {
          "desc":"ok",
          "status":"0",
          "pushContent":"xxx",
          "pushTime":"20190814180000",
          "creatTime":"Wed Aug 14 14:14:22 CST 2019",
          "sendResult":"DO_NOT_SEND"
    }
}

【任务】删除定时任务

功能说明

用来删除还未下发的任务,删除后定时任务不再出发

对应接口

IGeTui.delScheduleTask(taskId, appId)

限制说明

距离下发还有一分钟的任务,将无法删除,后续可以调用停止任务接口。

请求参数

名称 类型 是否必需 默认值 描述
taskId String 任务ID
appId String 应用唯一ID

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
taskDetail String 结果描述

返回示例

{
    "result":"Success",
    "taskDetail":""
}
开发者中心 SDK 下载

文档中心搜索