消息推送API

消息推送API

简述

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

  • toSingle :简称“单推”,指向单个用户推送消息
  • toList:简称“批量推”,指向制定的一批用户推送消息
  • toApp:简称“群推”,指向APP符合筛选条件的所有用户推送消息,支持定速推送、定时推送,支持条件的交并补功能

【toSingle】执行单推

描述

向单个clientid或别名用户推送消息。

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

应用场景

  • 场景1:某用户发生了一笔交易,银行及时下发一条推送消息给该用户。
  • 场景2:用户定制了某本书的预订更新,当本书有更新时,需要向该用户及时下发一条更新提醒信息。这些需要向指定某个用户推送消息的场景,即需要使用对单个用户推送消息的接口。

接口名称

pushMessageToSingle($message, $target, $requestId = null)

请求参数

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

SingleMessage

名称 类型 是否必需 默认值 描述
$isOffline boolean 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"
}

代码示例

<?php
//消息推送Demo
header("Content-Type: text/html; charset=utf-8");
require_once(dirname(__FILE__) . '/' . 'IGt.Push.php');

//采用"PHP SDK 快速入门", "第二步 获取访问凭证 "中获得的应用配置
define('APPKEY','');
define('APPID','');
define('MASTERSECRET','');
define('HOST','http://api.getui.com/apiex.htm');
define('CID','请输入您的CID');
//别名推送方式
//define('Alias','请输入您的Alias');

pushMessageToSingle();

//单推接口案例
function pushMessageToSingle(){
    $igt = new IGeTui(HOST,APPKEY,MASTERSECRET);

    //消息模版:
    // NotificationTemplate:通知模板
    $template = IGtNotificationTemplateDemo();

    //定义"SingleMessage"
    $message = new IGtSingleMessage();

    $message->set_isOffline(true);//是否离线
    $message->set_offlineExpireTime(3600*12*1000);//离线时间
    $message->set_data($template);//设置推送消息类型
    //$message->set_PushNetWorkType(0);//设置是否根据WIFI推送消息,2为4G/3G/2G,1为wifi推送,0为不限制推送
    //接收方
    $target = new IGtTarget();
    $target->set_appId(APPID);
    $target->set_clientId(CID);
//    $target->set_alias(Alias);

    try {
        $rep = $igt->pushMessageToSingle($message, $target);
        var_dump($rep);
        echo ("<br><br>");

    }catch(RequestException $e){
        $requstId =e.getRequestId();
        //失败时重发
        $rep = $igt->pushMessageToSingle($message, $target,$requstId);
        var_dump($rep);
        echo ("<br><br>");
    }
}

function IGtNotificationTemplateDemo(){
    $template = new IGtNotificationTemplate();
    $template->set_appId(APPID);                      //应用appid
    $template->set_appkey(APPKEY);                    //应用appkey
    $template->set_transmissionType(2);               //透传消息类型
    $template->set_transmissionContent("测试离线");   //透传内容
    $template->set_title("请填写通知标题");                     //通知栏标题
    $template->set_text("请填写通知内容");        //通知栏内容
    $template->set_logo("logo.png");                  //通知栏logo
    //$template->set_logoURL("http://wwww.igetui.com/logo.png"); //通知栏logo链接
    $template->set_isRing(true);                      //是否响铃
    $template->set_isVibrate(true);                   //是否震动
    $template->set_isClearable(true);                 //通知栏是否可清除
    $template->set_channel("set_channel");
    $template->set_channelName("set_channelName");
    $template->set_channelLevel(3);
    //$template->set_notifyId(12345678);
    return $template;
}
?>

【toSingle】执行批量单推

描述

用于一次创建提交多个单推任务。

应用场景

当单推任务较多时,推荐使用该接口,可以减少与服务端的交互次数。

接口名称

接口定义 说明
add($message, $target) 追加单推消息
submit() 提交消息
retry() 重新提交

请求参数:

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

注:此接口有批量个数有限制,alias不允许超过100个,cid不允许超过5000个。

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
info Array 每个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"
        }
    }
}

代码示例

<?php
//批量单推Demo
header("Content-Type: text/html; charset=utf-8");
require_once(dirname(__FILE__) . '/' . 'IGt.Push.php');
define('APPKEY','请输入您的APPKEY');
define('APPID','请输入您的APPID');
define('MASTERSECRET','请输入您的MASTERSECRET');
define('HOST','http://api.getui.com/apiex.htm');
define('CID1','请输入您的CID1');
define('CID2','请输入您的CID2');
pushMessageToSingleBatch();
function pushMessageToSingleBatch()
{
    $igt = new IGeTui(HOST, APPKEY, MASTERSECRET);
    $batch = new IGtBatch(APPKEY, $igt);
    $batch->setApiUrl(HOST);
    //$igt->connect();
    //消息模版:
    // 1.TransmissionTemplate:透传功能模板
    // 2.LinkTemplate:通知打开链接功能模板
    // 3.NotificationTemplate:通知透传功能模板
    // 4.NotyPopLoadTemplate:通知弹框下载功能模板

    //$template = IGtNotyPopLoadTemplateDemo();
    $templateLink = IGtNotificationTemplateDemo();
    $templateNoti = IGtNotificationTemplateDemo();
    //$template = IGtTransmissionTemplateDemo();

    //个推信息体
    $messageLink = new IGtSingleMessage();
    $messageLink->set_isOffline(true);//是否离线
    $messageLink->set_offlineExpireTime(12 * 1000 * 3600);//离线时间
    $messageLink->set_data($templateLink);//设置推送消息类型
    //$messageLink->set_PushNetWorkType(1);//设置是否根据WIFI推送消息,1为wifi推送,0为不限制推送,在wifi条件下能充分帮用户节省流量

    $targetLink = new IGtTarget();
    $targetLink->set_appId(APPID);
    $targetLink->set_clientId(CID1);
    $batch->add($messageLink, $targetLink);

    //个推信息体
    $messageNoti = new IGtSingleMessage();
    $messageNoti->set_isOffline(true);//是否离线
    $messageNoti->set_offlineExpireTime(12 * 1000 * 3600);//离线时间
    $messageNoti->set_data($templateNoti);//设置推送消息类型
    //$messageNoti->set_PushNetWorkType(1);//设置是否根据WIFI推送消息,1为wifi推送,0为不限制推送

    $targetNoti = new IGtTarget();
    $targetNoti->set_appId(APPID);
    $targetNoti->set_clientId(CID2);
    $batch->add($messageNoti, $targetNoti);

    try {
        $rep = $batch->submit();
        var_dump($rep);
        echo("<br><br>");
    }catch(Exception $e){
        $rep=$batch->retry();
        var_dump($rep);
        echo ("<br><br>");
    }
}

function IGtNotificationTemplateDemo(){
    $template =  new IGtNotificationTemplate();
    $template->set_appId(APPID);//应用appid
    $template->set_appkey(APPKEY);//应用appkey
    $template->set_transmissionType(1);//透传消息类型
    $template->set_transmissionContent("测试离线");//透传内容
    $template->set_title("请填写通知标题");//通知栏标题
    $template->set_text("请填写通知内容");//通知栏内容
    $template->set_logo("http://******");//通知栏logo
    $template->set_isRing(true);//是否响铃
    $template->set_isVibrate(true);//是否震动
    $template->set_isClearable(true);//通知栏是否可清除
    //$template->set_duration(BEGINTIME,ENDTIME); //设置ANDROID客户端在此时间区间内展示消息
    return $template;
}
?>

【toList】获取taskId

功能说明

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

操作步骤如下:

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

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

描述

一个应用同时下发了n个推送任务,为了更好地跟踪这n个任务的推送效果,可以把他们组成一个任务组,在查询数据时,只需要输入该任务组名即可同时查到n个任务的数据结果。任务组名有第三方填写

应用场景

  • 场景:做AB test,分别下发A组、B组推送任务,将A、B任务建成“任务组1”,查数据时,仅需要查找任务组1,即可以一起看到A、B两组测试的结果,可以更直观地对比数据。

对应接口

getContentId($message,$taskGroupName = null)

限制说明

注:此接口频次限制200万次/天,申请修改请点击右侧“技术咨询”了解详情 。

请求参数

名称 类型 是否必需 默认值 描述
$message ListMessage 消息体
$taskGroupName string 任务组名
多个消息公共体可以用同一个任务组名,后续可根据任务组名查询推送情况
  • 一个应用同时下发了n个推送任务,为了更好地跟踪这n个任务的推送效果,可以把他们组成一个任务组,在查询数据时,只需要输入该任务组名即可同时查到n个任务的数据结果。任务组名有第三方填写

ListMessage

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

返回参数

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

返回示例

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

【toList】执行批量推

功能说明

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

对应接口

pushMessageToList($contentId, $targetList)

限制说明

注:单次推送数量限制1000以内,此接口频次限制200万次/天,申请修改请点击右侧“技术咨询”了解详情 。

请求参数

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

Target

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

返回参数

名称 类型 描述
result String 请求结果,其他返回结果详见错误返回值
contentId String 就是taskId,任务ID
details Array 环境变量设置gexin_pushList_needDetails为true时返回此数据,不设置或为false不返还此数据。
aliasDetails Array 环境变量设置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"
     }
}

代码示例

<?php
//消息推送Demo
header("Content-Type: text/html; charset=utf-8");
require_once(dirname(__FILE__) . '/' . 'IGt.Push.php');

//采用"PHP SDK 快速入门", "第二步 获取访问凭证 "中获得的应用配置
define('APPKEY','');
define('APPID','');
define('MASTERSECRET','');
define('HOST','http://api.getui.com/apiex.htm');
define('CID1','请输入您的CID1');
define('CID2','请输入您的CID2');
//define('Alias1','请输入您的Alias1');
//define('Alias2','请输入您的Alias2');

pushMessageToList();

//多推接口案例
function pushMessageToList(){
    putenv("gexin_pushList_needDetails=true");
    $igt = new IGeTui(HOST,APPKEY,MASTERSECRET);
    //$igt = new IGeTui('',APPKEY,MASTERSECRET);//此方式可通过获取服务端地址列表判断最快域名后进行消息推送,每10分钟检查一次最快域名
    //消息模版:
    // NotificationTemplate:通知功能模板
    $template = IGtNotificationTemplateDemo();


    //定义"ListMessage"信息体
    $message = new IGtListMessage();
    $message->set_isOffline(true);//是否离线
    $message->set_offlineExpireTime(3600*12*1000);//离线时间
    $message->set_data($template);//设置推送消息类型
    $message->set_PushNetWorkType(0);//设置是否根据WIFI推送消息,1为wifi推送,0为不限制推送,在wifi条件下能帮用户充分节省流量
    $contentId = $igt->getContentId($message);
    //接收方1  
    $target1 = new IGtTarget();
    $target1->set_appId(APPID);
    $target1->set_clientId(CID1);
    //$target1->set_alias(Alias1);
    //接收方2
    $target2 = new IGtTarget();
    $target2->set_appId(APPID);
    $target2->set_clientId(CID2);
    //$target2->set_alias(Alias2);


    $targetList[0] = $target1;
    $targetList[1] = $target2;

    $rep = $igt->pushMessageToList($contentId, $targetList);
    var_dump($rep);
    echo ("<br><br>");
}

function IGtNotificationTemplateDemo(){
    $template = new IGtNotificationTemplate();
    $template->set_appId(APPID);                      //应用appid
    $template->set_appkey(APPKEY);                    //应用appkey
    $template->set_transmissionType(2);               //透传消息类型
    $template->set_transmissionContent("测试离线");   //透传内容
    $template->set_title("请填写通知标题");                     //通知栏标题
    $template->set_text("请填写通知内容");        //通知栏内容
    $template->set_logo("logo.png");                  //通知栏logo
    //$template->set_logoURL("http://wwww.igetui.com/logo.png"); //通知栏logo链接
    $template->set_isRing(true);                      //是否响铃
    $template->set_isVibrate(true);                   //是否震动
    $template->set_isClearable(true);                 //通知栏是否可清除
    $template->set_channel("set_channel");
    $template->set_channelName("set_channelName");
    $template->set_channelLevel(3);
    //$template->set_notifyId(12345678);
    return $template;
}
?>

【toApp】执行群推

功能说明

对指定应用的所有(或符合筛选条件的)用户群发推送消息。有定时、定速功能。
定速:全量推送时希望能控制推送速度不要太快,缓减服务器连接压力,可设置定速推送。如果未设置则按默认推送速度发送。
定时:对单个指定应用的所有用户群发推送消息。该消息可以在用户设定的时间点进行推送

限制说明

注:此接口频次限制100次/天,每分钟不能超过5次,定时推送功能需要申请开通才可以使用,申请修改请点击右侧“技术咨询”了解详情 。

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

接口名称

pushMessageToApp($message, $taskGroupName = null)

应用场景


  • 场景1:某app周年庆,群发消息给该app的所有用户,提醒用户参加周年庆活动。

请求参数

名称 类型 是否必需 默认值 描述
$message AppMessage 消息体
$taskGroupName String 任务别名
  • 一个应用同时下发了n个推送任务,为了更好地跟踪这n个任务的推送效果,可以把他们组成一个任务组,在查询数据时,只需要输入该任务组名即可同时查到n个任务的数据结果。任务组名有第三方填写

AppMessage

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

AppConditions

// AppConditions类的实例方法
addCondition3($key, $values, $optType=0)
名称 类型 是否必需 默认值 描述
key String 查询条件键(phoneType 手机类型,region 省市,tag 用户标签),其他key可开通VIP套餐,通过查询用户画像接口获取
values Array 查询条件值列表,其中
手机型号使用如下参数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"
}

代码示例

<?php
//消息推送Demo
header("Content-Type: text/html; charset=utf-8");
require_once(dirname(__FILE__) . '/' . 'IGt.Push.php');
define('APPKEY','请输入您的APPKEY');
define('APPID','请输入您的APPID');
define('MASTERSECRET','请输入您的MASTERSECRET');
define('HOST','http://api.getui.com/apiex.htm');

pushMessageToApp();
function pushMessageToApp(){
    $igt = new IGeTui(HOST,APPKEY,MASTERSECRET);
    $template = IGtNotificationTemplateDemo();
    //个推信息体
    //基于应用消息体
    $message = new IGtAppMessage();
    $message->set_isOffline(true); 
    // $message->setPushTime('201909021050');//在用户设定的时间点进行推送,格式为年月日时分
    // $message->set_speed(100);定速推送,设置setSpeed为100,则全量送时个推控制下发速度在100条/秒左右。
    $message->set_PushNetWorkType(0);//设置是否根据WIFI推送消息,2为4G/3G/2G,1为wifi推送,0为不限制推送,在wifi条件下能帮用户充分节省流量
    $message->set_offlineExpireTime(10 * 60 * 1000);//离线时间单位为毫秒,例,两个小时离线为3600*1000*2
    $message->set_data($template);

    $appIdList=array(APPID);
    $phoneTypeList=array('phoneType');
    // $provinceList=array('省份');
    // $tagList=array('tag');

    $cdt = new AppConditions();
    $cdt->addCondition3(AppConditions::PHONE_TYPE, $phoneTypeList);
    // $cdt->addCondition3(AppConditions::REGION, $provinceList);
    // $cdt->addCondition3(AppConditions::TAG, $tagList);

    $message->set_appIdList($appIdList);
    $message->set_conditions($cdt);

    $rep = $igt->pushMessageToApp($message);

    var_dump($rep);
    echo ("<br><br>");
}

function IGtNotificationTemplateDemo(){
    $template = new IGtNotificationTemplate();
    $template->set_appId(APPID);                      //应用appid
    $template->set_appkey(APPKEY);                    //应用appkey
    $template->set_transmissionType(2);               //透传消息类型
    $template->set_transmissionContent("测试离线");   //透传内容
    $template->set_title("请填写通知标题");                     //通知栏标题
    $template->set_text("请填写通知内容");        //通知栏内容
    $template->set_logo("logo.png");                  //通知栏logo
    //$template->set_logoURL("http://wwww.igetui.com/logo.png"); //通知栏logo链接
    $template->set_isRing(true);                      //是否响铃
    $template->set_isVibrate(true);                   //是否震动
    $template->set_isClearable(true);                 //通知栏是否可清除
    $template->set_channel("set_channel");
    $template->set_channelName("set_channelName");
    $template->set_channelLevel(3);
    //$template->set_notifyId(12345678);
    return $template;
}
?>

按城市接口推送

城市级别的推送基于个推原先的按省份推送的功能之上,使用同一个方法,这样可以减少开发者使用过程中的代码变更。省略具体的推送代码,下面展示相关变动的代码。

原来的省份推送是这样使用的:

$cdt = new AppConditions();
$provinceList=array('浙江','上海','北京');
$cdt->addCondition3(AppConditions::REGION, $provinceList);

现在按城市推送的使用方法如下:

$cdt = new AppConditions();
$provinceList=array('浙江','上海','北京');
array_push($provinceList, "33010000");   //杭州市
array_push($provinceList, "51010000");   //成都市
$cdt->addCondition3(AppConditions::REGION, $provinceList);

只需要在原有的列表里加入城市编号即可。

注1:编号对应表如region_code.data文件。

注2:列表里的城市仅支持编号表示,建议省份也用编号表示。为了兼容老用户,省份列表里的汉字仍能继续使用。

【任务】停止任务

功能说明

对正处于推送状态,或者未接收的消息停止下发(只支持批量推和群推任务)

接口名称

stop(taskId)

参数描述

参数名 类型 必需 默认值 参数描述
$taskId String 任务id(格式OSL-MMdd_XXXXXX或OSA-MMdd_XXXXXX)

返回参数

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

【任务】查询定时任务

描述

该接口主要用来返回 已提交的定时任务的相关信息。

接口名称

getScheduleTask($taskId,$appId)

参数说明

参数名 类型 必需 默认值 参数描述
$taskId String 任务ID
$appId String 应用ID

返回参数

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

taskDetail

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

返回示例

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

【任务】删除定时任务

描述

用来删除还未下发的任务

接口名称

delScheduleTask($taskId,$appId)

限制说明

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

参数说明

参数名 类型 必需 默认值 参数描述
$taskId String 任务ID
$appId String 应用ID

返回参数

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

返回示例

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

文档中心搜索

在线
咨询

微信扫一扫

随时联系技术支持

在线
咨询