小米手机全面屏手势提示线(虚拟键)适配说明

小米手机全面屏手势提示线(虚拟键)适配说明

1.背景

MIUI12将加入”手势提示线”,在设置-更多设置-全面屏中,可以通过开关打开/关闭该功能。手势提示线的实现原理参考了原生的方式,和虚拟按键在同一个window当中,可以理解成是虚拟按键的一种新的形态。

  • 适配的原则是:”手势提示线”(也就是虚拟键)的背景颜色和页面整体的背景颜色保持一致;
  • 主要有两种适配方式:”使用沉浸式虚拟键”和“给虚拟键设置合适的颜色”。

  图例为开启“手势提示线”效果                              图例为关闭“手势提示线”效果

2.使用沉浸式虚拟键

2.1如何设置

沉浸式虚拟键,即app的content view延伸到虚拟键区域,虚拟键的颜色透明。类似的,还有沉浸式状态栏,即app的content view延伸到状态栏区域,状态栏的颜色透明。

有两种设置的方式,参考代码如下。

方式1:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.test_layout);
 
    getWindow().addFlags(WindowManager.LayoutParams.FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS);
    getWindow().addFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_STATUS);       //设置沉浸式状态栏,在MIUI系统中,状态栏背景透明。原生系统中,状态栏背景半透明。
    getWindow().addFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_NAVIGATION);   //设置沉浸式虚拟键,在MIUI系统中,虚拟键背景透明。原生系统中,虚拟键背景半透明。
}

方式2:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.test_layout);
 
    getWindow().addFlags(WindowManager.LayoutParams.FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS);
    getWindow().setStatusBarColor(Color.TRANSPARENT);
    getWindow().setNavigationBarColor(Color.TRANSPARENT);
    getWindow().getDecorView().setSystemUiVisibility(
        View.SYSTEM_UI_FLAG_LAYOUT_STABLE|
        View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN|
        View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
    );
}

2.2可能存在的问题

设置了沉浸式虚拟键和沉浸式状态栏之后,状态栏和虚拟键会遮挡住app的内容,效果如下:

2.3解决方案

如果不希望app的内容被遮挡,可以给view设置  android:fitsSystemWindows=”true”,设置之后,系统会给该view自动加上paddingTop和paddingBottom。参考代码和效果如下:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/apps_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="#0000FF"
    android:fitsSystemWindows="true">

2.4适用的场景举例

当页面具有复杂的背景或纹理时:

3.给虚拟键设置合适的颜色

3.1如何设置

使用setNavigationBarColor来设置虚拟键的颜色。注意不要单独把颜色设置成透明,如果要设置成透明的话,参考上面的沉浸式虚拟键,配合其他flag使用。

参考下面的代码,按照这种方式设置之后,app的content view将不会延伸到虚拟键区域。

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.test_layout);
 
    getWindow().addFlags(WindowManager.LayoutParams.FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS);
    getWindow().setStatusBarColor(Color.BLUE);     //设置状态栏的背景颜色
    getWindow().setNavigationBarColor(Color.BLUE);  //设置虚拟键的背景颜色
}

3.2可能存在的问题

同一个应用往往有多个子页面,如果页面中背景颜色发生了变化,为了让虚拟键的颜色和页面的颜色保持一致,需要重新设置虚拟键的颜色,而不是统一给应用设置一个色值。

目前大部分业务已经适配了深色模式,因此在深色模式下还需要单独对虚拟键背景做深色适配。

3.3适用的场景举例

使用底部tab的颜色或者页面背景的颜色

小米商店上架APP权限用途用户告知适配说明

1.系统权限描述

MIUI11中,应政府对手机软件权限获取的合规要求,MIUI将支持三方应用通过向系统接口传输参数的方式,显示获取运行时权限的目的及用途,具体方案如下:

应用申请运行时权限时,可通过接口传输权限用途及描述,满足政府对于软件获取权限的合规要求,同时通过有效行为描述增加用户授权的可能性。

2.接口开放标准

2.1.填写权限使用申请

  • 仅支持通过小米应用商店上架的应用申请使用接口,申请时请按以下内容填写权限申请资料:
权限名称是否申请权限用途及说明(请提供简体中文及英语,中文字符不超过18个汉字)
Manifest.permission.READ_CONTACTS  
Manifest.permission.WRITE_CONTACTS  
Manifest.permission.GET_ACCOUNTS  
Manifest.permission.WRITE_CALENDAR  
Manifest.permission.SEND_SMS  
Manifest.permission.RECEIVE_SMS  
Manifest.permission.READ_SMS  
Manifest.permission.RECEIVE_MMS  
Manifest.permission.READ_EXTERNAL_STORAGE  
Manifest.permission.WRITE_EXTERNAL_STORAGE  
Manifest.permission.ACCESS_FINE_LOCATIONManifest.permission.ACCESS_COARSE_LOCATION  
Manifest.permission.READ_CALL_LOG  
Manifest.permission.WRITE_CALL_LOG  
Manifest.permission.PROCESS_OUTGOING_CALLS  
Manifest.permission.READ_PHONE_STATE  
Manifest.permission.READ_PHONE_NUMBERS  
Manifest.permission.CALL_PHONE  
Manifest.permission.ADD_VOICEMAIL  
Manifest.permission.USE_SIP  
Manifest.permission.ANSWER_PHONE_CALLS  
Manifest.permission.RECORD_AUDIO  
Manifest.permission.ACTIVITY_RECOGNITION  
Manifest.permission.CAMERA  
Manifest.permission.BODY_SENSORS  
  • 重要提示:以下权限,在MIUI 11 3.12 的开发版后将无法获取:
Manifest.permission.READ_PHONE_STATE

Manifest.permission.READ_PHONE_NUMBERS

Manifest.permission.CALL_PHONE Manifest.permission.ANSWER_PHONE_CALLS

2.2.发送权限申请至审核邮箱

填写权限使用申请后,请按如下格式将内容发送至miui-security-open@xiaomi.com

邮件主题:申请使用系统权限描述

【申请应用】填写应用名称

【应用包名】com.xxxx.xxxx

【公司主体】填写公司主体名称

【相关负责人】填写相关负责人

【联系方式】填写相关负责人联系方式

【权限申请目录】粘贴权限使用申请内容

2.3.等待审核

发送邮件后,请等待反馈,反馈时间在1-3个工作日内,若审核通过,将在反馈中提供调用方法并开设白名单。

2.4.技术接入

确定开放白名单后,请按以下方式接入:

申请示例:

private String[] permissions = new String[]{
        Manifest.permission.WRITE_EXTERNAL_STORAGE,
        Manifest.permission.CAMERA,
        Manifest.permission.RECORD_AUDIO,
        Manifest.permission.ACCESS_FINE_LOCATION
};



private String[] permissionDescs = new String[] {
        "存储用户精修美图",
        "拍摄抖音短视频",
        "游戏中进行语音交流",
        "获取地理位置来提供导航功能"
};


private List<String> mPermissionList = new ArrayList<>();
private static final int PERMISSION_REQUEST = 1;

//开始申请
for (int i = 0; i < permissions.length; i++) {
    if (ContextCompat.checkSelfPermission(this, permissions[i]) != PackageManager.PERMISSION_GRANTED) {
 mPermissionList.add(permissions[i]);
 mPermissionList.add(permissionDescs[i]);
    }
}
if (mPermissionList.isEmpty()) {
    //业务操作
} else {
    String[] permissions = mPermissionList.toArray(new String[mPermissionList.size()]);
    ActivityCompat.requestPermissions(MainActivity.this, permissions, PERMISSION_REQUEST);
}


//申请回调
@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
 if (requestCode == PERMISSION_REQUEST) {
        //业务操作
    }
}

 以上是最新推荐的申请权限的方式,只需要在申请的权限数组中加上对应的权限描述即可。

2.5.注意事项

权限及传入的权限描述要一一对应,权限描述不能传入null,若不需要描述,可传入空字符串:” “。

面向隐私保护的权限使用行为管理说明

1.背景

自MIUI于2010年8月16日上线以来,用户的隐私及安全都是我们最关注的要点。

小米于2018年起草《移动智能终端补充设备标识规范》,应对IMEI等设备标识被篡改及滥用的信息安全问题,确保用户数据隐私不被泄露。

在用户的隐私方面,MIUI希望可以通过系统权限隐私保护逻辑,在用户的隐私及数据安全方面有进一步的突破与保护措施。

2.权限改动

2.1.禁止获取不可重置的设备标识

  • 安卓P版本中将不再支持通过READ_PHONE_STATE权限获取不可重置的设备标识。具体表现与Android Q一致,获取到空值不抛出异常。
  • 生效时间:开发版-MIUI11 3.12(小米6)。
  • 针对READ_PHONE_STATE权限在Android P各MIUI版本的表现为:
版本/设备标识IMEI/MEIDIMSIICCIDSerialOAID
MIUI 11开发版(3.12之前)可以获取可以获取可以获取可以获取可以获取
MIUI 11稳定版可以获取可以获取可以获取可以获取可以获取
MIUI 11开发版(3.12之后)不可获取不可获取不可获取不可获取可以获取
  • 适配方法:可以通过”1″.equals(SystemProperties.get(“ro.miui.restrict_imei_p”))为true判断Android P上已经开启了设备标识的限制策略。
  • 建议开发者使用OAID替代IMEI等设备标识作为用户标识。OAID获取方法:http://msalliance.icoc.bz/col.jsp?id=120

2.2.CALL_PHONE 及 ANSWER_PHONE_CALLS

  • 除应用被设置为默认拨号应用外,CALL_PHONE权限及ANSWER_PHONE_CALLS将默认禁止获取。
  • 生效时间:开发版-MIUI11 3.12。
  • 适配方法:若业务需要以上两项权限,可从产品逻辑角度引导用户将应用设置为默认拨号应用。

2.3.禁用后台拍照行为

  • CAMERA权限仅支持应用在前台时调用,应用处于后台时将禁止使用该权限进行拍照或录像等行为。
  • 生效时间:开发版-MIUI11 3.12。
  • 适配方法:请开发者检查业务是否有相关行为并修改相关业务逻辑,避免出现异常情况;若出现不可避免的后台使用相机行为,请通过调起前台服务实现。

2.4.定位、录音权限用途描述

当应用申请定位、录音权限时,系统会根据应用是否对权限进行用户说明来判断授权弹窗中出现的选项:

  • 若应用未对权限用途进行说明,则显示“拒绝”“允许本次”及“仅在应用使用中允许”选项;
  • 若应用已进行权限用途说明,则在以上选项的基础上,增加显示“始终允许”选项。

该显示逻辑不影响基础权限选项,若用户进入应用授权管理,仍可对权限设置始终允许。

  • 生效时间:开发版-MIUI11 3.12。
  • 适配方法:请开发者进行权限用途说明,接入权限用途说明请查看:”MIUI权限用途接入说明“。

小米手机深色模式适配说明

小米手机深色模式适配说明

1.深色模式背景与介绍

1.1.安卓原生深色模式介绍

Android 10 (API 级别 29) 及更高版本中提供深色主题背景。深色主题背景具有诸多优势:

  • 可大幅减少耗电量(具体取决于设备的屏幕技术)。
  • 为弱视以及对强光敏感的用户提高可视性。
  • 让所有人都可以在光线较暗的环境中更轻松地使用设备。

深色主题背景同时适用于 Android 系统界面和在设备上运行的应用。在 Android 10 (API 级别 29) 及更高版本中,您可以通过以下三种方法启用深色主题背景:

  • 使用系统设置(Settings -> Display -> Theme)启用深色主题背景。
  • 使用“快捷设置”图块,从通知托盘中切换主题背景(启用后)。
  • 在 Pixel 设备上,选择“省电模式”将同时启用深色主题背景。其他原始设备制造商 (OEM) 不一定支持这种行为。

可参考:https://developer.android.com/guide/topics/ui/look-and-feel/darktheme#top_of_page

1.2.MIUI深色模式介绍

深色模式是一种将屏幕主色调转为深色的模式。如下图MIUI10界面为例,上图是正常浅色背景,下图为MIUI深色模式。

用户在MIUI中有两个方式可以打开深色模式:1.设置-显示-深色模式 2.下拉控制中心 中可以开启,开启后将全局变黑如上图显示:

对于适配深色模式的应用来说,我们会优先启用应用的深色模式。未接入的应用,则会通过算法进行反色。适配方式将在第三部分详细描述。如果用户不希望某个应用被反色,用户可以手动关闭该应用的反色功能,见下方:

目前已有众多知名头部三方应用适配了深色模式,例如微信、QQ、爱奇艺、优酷、知乎、小红书、钉钉等。

2.适配深色模式的好处

我们强烈建议您为您的应用适配深色模式,主要有如下原因:

  • 更酷、更时髦的流行趋势

作为一种全新的潮流,黑色界面受到众多用户、尤其是年轻用户的欢迎。目前,各大安卓系统、iOS系统都已经支持深色模式,众多主流头部应用也已适配或正在适配深色模式。                

  • 让用户更专注于内容

深色背景下,文字、图片、视频都能更清晰地呈现,尤其是暗光环境下。对于浏览器、资讯和视频类app,深色可以让用户沉浸其中,为应用贡献更多的使用时长:对于使用时段是晚上的应用,这一特性更加明显。                                               

  •  降低应用的耗电量                                               

省电是用户最关注的性能之一。低电情况下,用户更青睐使用深色模式的应用。根据小米实验室测试数据:

OLED屏幕100%亮度下,深色模式耗电相比浅色模式,最高降低83%;

OLED屏幕50%亮度下,深色模式耗电相比浅色模式,最高降低50%。

  • 推广优待适配深色模式时可以联系我们,小米可以为应用提供应用商店专题和微博宣传等方式,为应用增加额外的宣传。

3.适配方式

适配方式有两种:

  • 适配深色模式资源:开发者根据自身应用设计深色模式,按照适配规范进行适配。
  • 适配全局反色:利用安卓Q上提供的forcedark能力可以直接反色。

在适配前,开发者需要考虑是否在自有应用内增加深色模式开关。我们建议的方式:

  • 务必提供跟随系统深色模式的选项。可以默认跟随系统,或在监测到系统切换为深色/浅色时提示用户。 
  • 可以为用户提供手动切换的开关。

目前已有三方应用如下(左 小红书 右 QQ),仅供参考:

方式一 适配深色模式资源                                           

适配深色模式资源需要设计师先对所有页面设计深色页面,再由开发完成深色模式资源开发。

优点:在所有安卓版本、所有手机厂商用户均可以使用,且体验较好。

3.1.谷歌适配要求

开发者可基于谷歌深色模式适配标准进行适配:https://developer.android.com/guide/topics/ui/look-and-feel/darktheme#top_of_page

已经适配过的页面要将ForceDarkAllowed()​参数值设置为false,若整个主题均已适配深色模式,则需要将这个主题的ForceDarkAllowed()参数值设置为false。

3.2.小米深色模式配色标准设计

其余适配建议详见设计文档:附件1-小米深色模式配色标准设计文档。

3.3.接入方式

3.3.1.接入介绍

  • 根据谷歌深色模式接入标准,如要支持深色主题背景,您必须将应用的主题背景(通常可在res/values/styles.xml中找到)设置为继承 ​DayNight​ 主题背景:
<style name="AppTheme" parent="Theme.AppCompat.DayNight">

您还可以使用 MaterialComponent 的深色主题背景

<style name="AppTheme" parent="Theme.MaterialComponents.DayNight">

这会将应用的主要主题背景与系统控制的夜间模式标记相关联,并将应用的默认主题背景设置为深色主题背景(如果已启用)。详细内容见:https://developer.android.com/guide/topics/ui/look-and-feel/darktheme#force_dark

从开发的角度说,就是打开夜间模式后,系统会优先从xxx-night资源中寻找资源并替换。
Android系统从2.2开始就已经⽀支持了了DarkMode,其对应接口是名为“uimode”的系统服务,DarkMode所使⽤用到的接口方法是:setNightMode、getNightMode分别对应设置夜间模式和获取设置状态。

// 获取uimode系统服务
UiModeManager uiModeManager = (UiModeManager)
getSystemService(Context.UI_MODE_SERVICE);                                             
// 获取设置状态
int currentMode = uiModeManager.getNightMode();                                               
// 设置夜间状态
uiModeManager.setNightMode(UiModeManager.MODE_NIGHT_AUTO); // ⾃动
uiModeManager.setNightMode(UiModeManager.MODE_NIGHT_YES); // 启⽤
uiModeManager.setNightMode(UiModeManager.MODE_NIGHT_NO); // 停⽤
                                             
在日志中的体现:
------------------------------------------------------                                                        
DUMP OF SERVICE uimode:
Current UI Mode Service state:                                                        
mDockState=0 mLastBroadcastState=0                                                        
mNightMode=2 mNightModeLocked=false
mCarModeEnabled=false mComputedNightMode=false
mCarModeEnableFlags=0 mEnableCarDockLaunch=true                                                        
mCurUiMode=0x2d mUiModeLocked=false mSetUiMode=0x2d
mHoldingConfiguration=false mSystemReady=true
mTwilightService.getLastTwilightState()=null                                                        
--------- 0.001s was the duration of dumpsys uimode,ending at: 2019-01-18 00:00:01--------------

从uimode服务dump出来的信息可以判断:

mNightMode的取值:0 → AUTO; 1 → NO; 2 → YES另外,在Android O开始,Android⽀支持adb命令启动和停⽤用DarkMode,具体命令是:adb shell cmd uimode night <auto | yes | no>

O以前的机型,只能通过代码调用uimode接口启动和停用DarkMode。需要注意的是,miui虽然从level 16开始支持DarkMode,但是并不意味着miui之前的版本不能切换DarkMode,用户完全可以通过命令或者代码调用系统接口,启动和关闭DarkMode。而Setting中的开关是阻⽌不了的,除⾮MIUI对这个权限进行收紧。   

MIUI SDK从level 16开始,支持DarkMode,所以的支持DarkMode,是指MiuiSDK增加了新的主题,DayNight,来自适应的适配Light和Dark主题。其实在16之前的SDK上,Light和Dark主题都是一直存在的,只是没有一个自动适配的机制存在,而且Dark主题存在一些Bug,并不是它应该是的样⼦。适配过程中,存在一些APP,之前就是在Dark主题下进行的开发,那么在sdk level 16以后,发现Dark模式存一些问题,比如弹窗变成了⿊⾊,均是因为Dark主题修改造成的。附录中会给出SDK针对Dark和Light进行的改动,包括所有受影响的资源和主题样式修改。

3.3.2.接入方式详细说明                                              

重点说明⼀下接⼊和使⽤⽅式。这⾥除了Theme.Light.DarkActionBar这个主题以外,所有Light(Dark)主题均有对应的DayNight主题。

  • 对于非解耦应⽤,可以直接使⽤Miui SDK的public的资源和属性。

代码接⼊方式:可以直接将使⽤MiuiSdk的Light或者Dark主题的地方,替换成DayNight主题,⽐如:将

<style name="MiuiDemo.Theme.Test" parent="miui:Theme.Light">
或者<style name="MiuiDemo.Theme.Test" parent="miui:Theme.Dark"> 
替换成<style name="MiuiDemo.Theme.Test" parent="miui:Theme.DayNight">

Java代码中:将使⽤Light主题的所有地⽅miui.R.style.Theme_Light替换成miui.R.style.Theme_DayNight

  • (如果本身就是⾃升级应用,就不⽤看这⼀步了)对于解耦自升级应⽤,需要在gradle中进行如下操作:   
1)修改build.gradle中的dependencies,使⽤用miui插件,如下:(以gradle 3.3.0为例)
dependencies {                                               
classpath 'com.miui.tools.build:gradle:3.3.0'
}
2)gradle/wrapper/gradle-wrapper.properties⽂文件中的gradle修改到5.0,即:
distributionUrl=http://sdk.pt.miui.com/miuisdk/software/gradle/gradle-5.0-all.zip
3)此步,3.2.0可以忽略略,在3.3.0下必须将:                                                
apply plugin: 'com.android.application'
改成
apply plugin: 'com.miui.application'                                       
4)如果gradlew的⽇日志中有如下输出:
add property to gradle.properties of this project:                                                
android.aapt2FromMavenOverride=/home/{username}/.miuisdk/build-tools/aapt/28/aapt2
则修改gradle.properties,最后加一行:
android.aapt2FromMavenOverride=//home/{username}/.miuisdk/build-tools/aapt/28/aapt2
5)增加依赖:
compileOnly 'com.miui:core:alpha-SNAPSHOT'

于是,miui sdk中的Theme.DayNight就接入完成,在APP中可以直接使⽤Theme.DayNight.<…>主题。针对之前的miui:Theme.Light主题或者miui:Theme.Dark主题,均有对应的Dark或者Light主题。所以,如果需要适配自动切换夜间和日间模式,只要替换成对应的DayNight主题即可,DayNight主题负责⾃动切换两种(Dark和Light)主题。

  • (非单发应⽤请忽略)对于单发应用:单发应用的接⼊⽅式,可以参考:MIUI SDK support包的使用指南将依赖由:compileOnly ‘com.miui:core:alpha-SNAPSHOT’改成 implementation ‘com.miui.support:core-compat:alpha-SNAPSHOT’
  • 对于单发或者⾃升级应⽤,在代码接入上完全可以参考1中的代码接入方式。即,替换Light或者Dark为DayNight。但是,对于⾃自升级来说(单发应⽤不会有这个问题,因为单发应用已经将DayNight主题打包进APK),由于不确定⾃升级的目标ROM是否⽀持DayNight主题,所以如果在没有DayNight主题的ROM上⾃自升级,就会崩溃。这⾥需要看下⾯的注意事项1,可以找到解决方案。详见开发文档:附件2-深色模式开发文档

方式二 适配全局反色

全局反色利用安卓Q上提供的forcedark能力可以直接反色,对于开发者来说较为友好。

  • 优点:开发工作量小,适配较快。
  • 缺点:仅安卓Q手机可以使用该功能,复杂页面用forcedark适配难度较大;非原生的Webview无法反色,图片无法反色。

可以在安卓Q手机上,打开以下开关即可体验安卓Q反色能力,查看本应用反色后的情况。开关位置如下:

3.4.谷歌Force Dark适配要求

Android 10 提供 Force Dark 功能。一如其名,此功能可让开发者快速实现深色主题背景,而无需明确设置 ​DayNight​ 主题背景。如果您的应用采用浅色主题背景,则 Force Dark 会分析应用的每个视图,并在相应视图在屏幕上显示之前,自动应用深色主题背景。有些开发者会混合使用 Force Dark 和本机实现,以缩短实现深色主题背景所需的时间。应用必须选择启用 Force Dark,方法是在其主题背景中设置 ​android:forceDarkAllowed=”true”​。此属性会在所有系统及 AndroidX 提供的浅色主题背景(例如 ​Theme.Material.Light​)上设置。使用 Force Dark 时,您应确保全面测试应用,并根据需要排除视图。如果您的应用使用深色主题背景(例如​Theme.Material​),则系统不会应用 Force Dark。同样,如果应用的主题背景继承自 DayNight​主题背景,则系统不会应用 Force Dark,因为会自动切换主题背景。

3.5.MIUI深⾊模式适配的目标和方法

在MIUI12上推出全局的深色模式,所有系统应用和主流三方应用适配。在MIUI12上用户开启深色模式后将默认开启全局反色。要达到的效果:系统切换到深⾊模式以后,应⽤也随之切换到深色模式,这是我们这次MIUI适配深色模式要达到的目标,也是我们对每个系统应⽤的要求。

适配的⽅法有三种:                                          

  • Android原生的深色主题
  • 全局反⾊
  • 第三方框架或者应用⾃自己实现深色模式  

目前只有Android Q深色模式支持全局反色:Android Q上提供了两种实现深色模式的⽅式:深色主题和全局反⾊。

深⾊主题即Theme.AppCompat.DayNight或者Theme.MaterialComponents.DayNight。深⾊主题是Android官⽅提供的实现深色模式的一种方法,应用也可以其它自己的方法实现深色模式。深⾊主题起作用后,将会加载-night⽬目录下的资源,如果没有找到,那么加载默认资源。对于标准控件,如果应用不提供深色模式的资源,系统也会提供一套默认的深色资源(不过比较难看,基本不可用)全局反色即ForceDark,系统会根据一套算法,计算出每个View属于前台还是后台。对于前台View,会使其变亮,对于后台View,会使其变暗,⽽不需要开发者提供两套资源。具体的原理可以移步Android Q Force Dark调研。如果一个activity使⽤了深色模式,那么全局反色对其将不生效。    

3.6.接入方式介绍

3.6.1.建议的整体适配步骤                                              

  • 现状评估

打开系统的深⾊模式,看看⾃⼰应用中那些⻚面有没有问题,一般可以分为三类:

A.适配了深色模式没有问题

B.没有适配深色模式的

C.适配了深⾊模式但是有问题的

  • 全局反色过滤

对于所有的A,请务必禁用全局反色,否则全局反色可能会和已有的深⾊模式效果冲突。对于所有的B,可以设置 <item name=”android:forceDarkAllowed”>true</item> ,然后可以打开全局反色,观察有没有问题。没有问题的,那就适配完成了,问题⽐较⼤的归为D。

  • 全局反色问题分析                                       

对于所有的D,分析问题的原因,是反色本身的问题还是⾃己应⽤导致的,⽐如布局存在有问题,有图片、webVIew等。其他的看下能不能通过调整布局等最后还是通过全局反⾊简单解决,剩下统一归为C。

  • 重新适配

对于C,看看是不是原来的适配方法有问题,有没有必要采用新的适配⽅法、框架,可不可以采用系统的深色主题等重新适配。                                              

  • 验证

打开系统深色模式,重新测试所有页⾯。

比较理想的做法是:建议采用深色主题和全局反色相结合的方式。整个应用用的主题使用DayNight,设置<item name=”android:forceDarkAllowed”>false</item>。对于已经⽀持深色主题或者用其他方法实现了深⾊模式的⻚面,没必要再支持全局反⾊,务必禁⽤。对于需要使用反⾊的⻚面,使⽤Light主题,设<itemname=”android:forceDarkAllowed”>true</item>。其他⻚面单独适配。                                             

3.6.2.深色主题的适配

深色主题在Android Q之前就是已经有了的,只不过其在Android Q上得到了了加强。一个activity如果想使用深色主题,让其主题继承于DayNight主题或者让整个应用的主题继承于DayNight主题即可。不过,上⾯的做法只适合跟随系统变化的需求,如果有高级的需求,⽐如应用想要主动切换到深⾊色主题或者不跟随系统变化,而是让⽤户选择,那么需要这样做:

1.监听UImode的变化。manifest中 activity 设置属性 android:configChanges=”uiMode”,并重写onConfigurationChanged。注意,声明了configChanges系统将不不会重建对应的activity,⽽而是回调onConfigurationChanged,需要activity⾃己处理变化的情况

2.让Activity继承于AppCompatActivity,这样子可以通过AppCompatDelegate.setDefaultNightMode(mode) 设置当前activity的mode,通过AppCompatDelegate.getDefaultNightMode()获取当前设置的mode。系统可以选择的mode有四种,具体解释可以看下面第1篇文章。

3.用户选择夜间模式的时候,保存用户选择的模式到SharedPreferences,调用recreate()重启activity,注意recreate()是重新创建activity,会回调所有生命周期方法。

4.activity启动的时候,取出之前保存的模式,通过AppCompatDelegate.setDefaultNightMode(mode) 进行当前activity的mode。                                            

5.系统UImode发⽣变化的时候,即onConfigurationChanged时,获取系统当前的UImode,根据应用⾃身的逻辑判断需不需要改变当前activity的mode,如果需要改变重复第3、4步。

切换到深⾊模式时,资源应用的顺序:                                  

  • 应用提供的-night资源
  • 应⽤设置的默认资源(通常是亮色下的资源,也可以是应用主动在深⾊模式下设置的主题)
  • 系统的默认深⾊资源
  • 系统默认的亮色资源

所以,凡是应用⾃己提供资源了的,那就提供两套,要么就全部⽤用系统的默认资源。如果一个应⽤没有使用DayNight主题,那么只会变化应用提供的-night深⾊资源,其他不会变化,系统也不会应⽤标准控件的默认深色资源。

具体实现,可以参考:  

https://segmentfault.com/a/1190000011472198
https://blog.csdn.net/xiaoxiaocaizi123/article/details/90370275

有两种方式,⼤同小异,相信大家能看得懂。

3.6.3.全局反色的适配      

⾸先来看下全局反色生效前提:

系统端:1.开启深色模式

应用端:1.activity对应的主题是Light的 2.对应的控件允许全局反色,默认是forceDarkAllowedDefault,这个值由系统属性debug.hwui.force_dark决定,debug.hwui.force_dark⼜是由全局反⾊的开关控制,默认是关闭的。         

以上几点缺⼀不可,需要详细说明几点是:

1.实现了深色主题的activity是不会受全局反色的影响,前面说了,深⾊主题是DayNight,不属于Light

2.如果一个控件没有申明forceDarkAllowed,那么forceDark是否⽣效取决于全局反色是否开启,如果全局反色开启,那么forceDark生效,否则不生效;

如果一个控件声明了forceDarkAllowed = false,那么无论如何都不会生效;

如果一个控件声明了forceDarkAllowed = true,那么只要开启深色模式,全局反色就会⽣效。             

3.forceDarkAllowed可以在主题xml中申明,也可以在代码中动态设置,动态设置可以具体到某⼀个view,后者会覆盖前者。遵循覆盖原则,即子View的声明会覆盖父View的声明,activity的会覆盖这个应⽤的申明。

适配全局反色的步骤:                                                

1.compileSdkVersion 设为29, 否则会编译失败,targetSdkVersion 貌似没有要求。

2.对于需要使用forceDark的activity,务必让其实现Light主题,Dark主题、DayNight主题都不会⽣效。

3.在activity的主题中申明<item name=”android:forceDarkAllowed”>true</item> 或者 在onCreate中,在setContentView之前,调⽤getWindow().getDecorView().setForceDarkAllowed(allowed)。

最后提供demo,需要的可以参考一下,源码:https://github.com/CQULittleMing/AndroidDemo/tree/master/demo

操作路径:  View – View 下面最后的两个。     

4.FAQ

4.1.全局反色的局限

  • 目前全局反色只是实验性功能,存在很多bug,不可过于依赖,更多可以参考Force Dark目前存在的问题。
  • 不会反色图⽚。
  • WebView/Flutter⽀持不完善所以如果一个⻚面存在Flutter书写、WebView或者亮色的图片,建议还是使⽤深色模式进行适配。

4.2.如何开启和禁用全局反色

设置是否⽀持全局反色有静态和动态两种方法:                                              

静态方式就是对应用或者activity的主题中声明<item name=”android:forceDarkAllowed”>true</item> 或者 <item name=”android:forceDarkAllowed”>false</item>;

动态⽅法是调用View.setForceDarkAllowed(true)或者View.setForceDarkAllowed(false),对DecorView设置可以对整个窗口起作⽤。

5.联系我们

有任何问题可以随时联系我们:

商务合作:liushuo3@xiaomi.com

产品问题:zhangyanan10@xiaomi.com

研发问题:darkmode@xiaomi.com

小米手机&平板设备规格

本文档描述了小米手机各个型号及小米平板的软硬件规格

表1:小米手机4、小米手机3联通&电信版、红米手机1S 3G&4G移动版、红米手机1S 3G联通版&电信版

项目小米手机4小米手机3联通&电信版红米手机1S 3G&4G移动版红米手机1S 3G联通版&电信版
屏幕尺寸5.0英寸5.0英寸4.7英寸4.7英寸
系统识别屏幕尺寸NORMALNORMALNORMALNORMAL
屏幕分辨率1920 * 10801920 * 10801280 * 7201280 * 720
像素密度xxhdpixxhdpixhdpixhdpi
CPU骁龙™ 8X74AC 801 四核高通骁龙 800 8274AB 四核MTK MT6582四核(联)高通骁龙400 MSM8228(电)高通骁龙400 MSM8628
GPUAdreno 330Adreno 330Mali-400Adreno 305
内存3072MB2048MB1024MB1024MB
WiFi802.11 a/b/g/n/acWIFI Display WIFI Direct 5GHzWiFi 802.11b/g/n802.11b/g/n
蓝牙BT4.0 + HIDBT4.0 + HIDBT4.0LE +BT3.0HSBT4.0 + HID
定位服务GPS + GLONASS +AGPS+北斗GPS+GLONASS AGPSGPS + AGPSGPS AGPS+GLONASS
系统版本Android 4.4+Android 4.2.1+Android 4.2+Android 4.3+
系统存储16G/64G16G/64G8G8G
外置存储Micro SDMicro SD
后置摄像头
前置摄像头
触摸屏10点触摸10点触摸10点触摸10点触摸
android.os.Build. MANUFACTURERXiaomiXiaomiXiaomiXiaomi
android.os.Build. MODELMI 4WMI 3W&MI 3CHM 1STD HM2014501HM 1SC HM 1SW
陀螺仪支持支持支持支持
距离感应器支持支持支持支持
光线传感器支持支持支持支持
加速度传感器支持支持支持支持
OTG支持支持支持支持
NFC支持

表2: 小米平板、红米手机Note 3G版、红米Note 4G 增强版

项目小米平板红米手机Note 3G版红米Note 4G 增强版
屏幕尺寸7.9英寸5.5英寸5.5英寸
系统识别屏幕尺寸Extra LargeNORMALNORMAL
屏幕分辨率2048 * 15361280 * 7201280 * 720
像素密度xhdpixhdpixhdpi
CPUNVIDIA Tegra K1 四核MTK MT6592 八核高通骁龙400 MSM8928 四核
GPUNVIDIA KeplerARM Mali-450Adreno 305
内存2048MB2048MB1024MB
WiFiWiFi Display/WiFi Direct802.11b/g/n802.11 a/b/g/n/ac
蓝牙BT4.0BT3.0HS+BT4.0(移) BT4.0LE +BT3.0HS(联)BT4.0LE
定位服务不支持GPS定位GPS+AGPSGPS+AGPS +GLONASS +北斗定位
系统版本Android 4.4+Android4.2+Android4.4+
系统存储16G/64G8G8G
外置存储
前置摄像头
后置摄像头
触摸屏10点触摸10点触摸10点触摸
android.os.Build. MANUFACTURERXiaomiXiaomiXiaomi
android.os.Build. MODELMI PADHM NOTE 1LTETD /HM NOTE 1LTEWHM NOTE 1LTETD
陀螺仪支持支持支持
光线传感器支持支持支持
加速度传感器支持支持支持
距离感应器不支持支持支持
OTG支持支持支持
NFC
电子罗盘支持支持支持
气压计不支持支持支持

表3: 小米手机2S、小米手机2A、红米手机、小米手机3 TD版

项目小米手机2S小米手机2A红米手机小米手机3 TD版
屏幕尺寸4.3英寸4.5英寸4.7英寸5.0英寸
系统识别屏幕尺寸NORMALNORMALNORMALNORMAL
屏幕分辨率1280 * 7201280 * 7201280 * 7201920 * 1080
像素密度xhdpixhdpixhdpixxhdpi
CPU高通 骁龙600 1.7G四核高通 骁龙S4 Pro 1.7G双核MTK MT6589T Tagra 4NVIDIA Tegra 4
GPUAdreno 320Adreno 320PowerVR SGX 544MPTagra
内存2048MB1024MB1024MB2048MB
WiFiWIFI Display WIFI DirectWIFI Display WIFI DirectWIFI DirectWIFIDisplay/WIFI Direct
蓝牙BT4.0 + HIDBT4.0 + HIDBT4.0LE +BT3.0HSBT4.0 + HID
定位服务GPS + GLONASS AGPSGPS + GLONASS AGPSGPS + AGPSGPS + GLONASS AGPS
系统版本Android 4.1+Android 4.1+Android 4.2.1+Android 4.2.1+
系统存储16G/32G16G4G16G/64G
外置存储Micro SD
后置摄像头
前置摄像头
触摸屏10点触摸10点触摸10点触摸10点触摸
android.os.Build. MANUFACTURERXiaomiXiaomiXiaomiXiaomi
android.os.Build. MODELMI 2S 或 MI 2SCMI 2A2013022MI 3
陀螺仪支持支持支持支持
距离感应器支持支持支持支持
光线传感器支持支持支持支持
加速度传感器支持支持支持支持
OTG支持支持支持支持
NFC支持支持

表4: 小米手机、小米手机1S、1S青春版、小米手机2

项目小米手机小米手机1S1S青春版小米手机2
屏幕尺寸4.0英寸4.0英寸4.0英寸4.3英寸
系统识别屏幕尺寸NORMALNORMALNORMALNORMAL
屏幕分辨率854 * 480854 * 480854 * 4801280 * 720
像素密度hdpihdpihdpixhdpi
CPU高通 MSM8x60 1.5G双核高通 MSM8260 1.7G双核高通 MSM8260 1.5G双核高通 APQ8064 1.5G四核
GPUAdreno 220Adreno 220Adreno 220Adreno 320
内存1024MB1024MB1024MB2048MB
WiFi
蓝牙BT2.1BT2.1BT2.1BT4.0 + HID
定位服务GPS + AGPSGPS + AGPSGPS + AGPSGPS + GLONASS AGPS
系统版本Android 2.3+Android 2.3+Android 2.3+Android 4.0.3+
系统存储4G4G4G16G/32G
外置存储Micro SDMicro SDMicro SD
后置摄像头
前置摄像头
触摸屏10点触摸10点触摸10点触摸10点触摸
android.os.Build. MANUFACTURERXiaomiXiaomiXiaomiXiaomi
android.os.Build. MODELMI-ONE PlusMI 1S M1 1SCMI 1S M1 1SCMI2
陀螺仪支持支持支持支持
距离感应器支持支持支持支持
光线传感器支持支持支持支持
加速度传感器支持支持支持支持
OTG支持
NFC

文件过滤以及芯片支持的技术文档

小米手机3TD版和小米平板使用的是NVDIA的显卡,apk的supports-gl-texture声明中至少有一个texture是该设备支持的texture。这也是该apk在小米应用商店中不被过滤,可以被现实的前提。 文件过滤以及芯片支持的技术文档 Android的所有应用,都可以通过其中的AndroidManifest.xml文件中的< supports-gl-texture >标签声明该apk文件支持的gl-texture。 同时,设备根据GPU的不同支持的gl-texture也不相同。 小米手机3TD版和小米平板使用的是NVDIA的显卡,apk的supports-gl-texture声明中至少有一个texture是该设备支持的texture。这也是该apk在小米应用商店中不被过滤,可以被现实的前提。

  • 小米平板支持的gl-texture GL_EXT_color_buffer_half_float, GL_EXT_debug_label, GL_EXT_debug_marker, GL_EXT_map_buffer_range, GL_EXT_robustness, GL_EXT_texture_compression_dxt1, GL_EXT_texture_compression_s3tc, GL_EXT_texture_format_BGRA8888, GL_EXT_unpack_subimage, GL_KHR_debug, GL_NV_bgr, GL_NV_secure_context, GL_NV_texture_compression_s3tc, GL_OES_EGL_image, GL_OES_EGL_image_external, GL_OES_EGL_sync, GL_OES_compressed_ETC1_RGB8_texture, GL_OES_compressed_paletted_texture, GL_OES_draw_texture, GL_OES_element_index_uint, GL_OES_fbo_render_mipmap, GL_OES_framebuffer_object, GL_OES_matrix_get, GL_OES_packed_depth_stencil, GL_OES_point_size_array, GL_OES_point_sprite, GL_OES_read_format, GL_OES_rgb8_rgba8, GL_OES_stencil8, GL_OES_texture_cube_map, GL_OES_texture_npot, GL_OES_vertex_half_float,
  • 小米手机3 TD版支持的gl-texture GL_EXT_bgra, GL_EXT_debug_label, GL_EXT_debug_marker, GL_EXT_texture_compression_dxt1, GL_EXT_texture_compression_s3tc, GL_EXT_texture_format_BGRA8888, GL_EXT_unpack_subimage, GL_NV_texture_npot_2D_mipamap, GL_OES_EGL_image, GL_OES_EGL_image_external, GL_OES_EGL_sync, GL_OES_byte_coordinates, GL_OES_compressed_ETC1_RGB8_texture, GL_OES_compressed_paletted_texture, GL_OES_draw_texture, GL_OES_extended_matrix_palette, GL_OES_fbo_render_mipmap, GL_OES_fixes_point, GL_OES_framebuffer_object, GL_OES_matrix_get, GL_OES_matrix_palette, GL_OES_point_size_array, GL_OES_point_sprite, GL_OER_query_martrix, GL_OES_read_format, GL_OES_rgb8_rgba8, GL_OES_single_precision, GL_OES_stencil8, GL_OES_texture_cube_map, GL_OES_vertex_half_float,

VersionCode和VersionName是什么意思?

VersionCode和VersionName是什么意思?

各位Android应用开发爱好者和运营团队在小米应用商店的运营中,常常遇到因为不明白一些Android的概念而造成的困扰。因此我们准备了一些基础知识。

一、简单讲讲

Google为APK定义了两个属性:VersionCode和VersionName,他们有不同的用途。

  • VersionCode:对消费者不可见,仅用于应用市场、程序内部识别版本,判断新旧等用途。
  • VersionName:展示给消费者,消费者会通过它认知自己安装的版本,下文提到的版本号都是说VersionName。

结尾有三个常见问题的解决方案

  • 同一个版本号,对应了多个VersionCode怎么办
  • 发布了一个VersionCode错误的版本怎么办
  • 发出去的应用有Bug要换回旧版,怎么操作?

二、然后讲讲前因后果

大家在使用软件和应用时,都会涉及到版本的概念,大家都知道的,比如Win XP,QQ2012,小米桌面1.6。之所以会有版本,主要是因为软件产品一直在发展、变化的。版本的概念可以帮助消费者识别不同时期的产品。

而展现在消费者面前的版本,和开发者内部使用的通常是不同的版本。开发时通常会使用数字作为标志,比如6.1.7600.16385,其实是Win 7第一个正式版的版本号,而Win 7 SP1的版本号是6.1.7601.17514,这样长长一串数字对消费者毫无意义,所以在产品发布时通常会起一个更容易懂的版本。下文中会把Win 7这样的用于展示的版本叫做[VersionName],6.1.7601.17514这样用于程序标识的版本叫做[VersionCode]

早年因为软件主要自己负责自己的分发、升级等方面,所以版本号也相当自由,各家都有不同的规范。但是近年来移动设备崛起,AppStore这样的应 用商店集中分发成了主流。以升级为例,应用商店会负责检查消费者手机上应用的版本,并和商店里面最新的版本比较,如果商店里面的版本比较新,消费者手机上 的版本比较旧,就会提醒消费者升级。

这就涉及到如何识别新、旧的问题。 对于计算机来说,最可靠的判断方式就是数字,数字有很多好处:程序容易判断、格式简单不容易出错、肉眼容易识别等。所以Google要求每个应用都要在 APK安装包中记录这个安装包的[VersionCode],只要拿到这个APK文件,就可以知道它对应的[VersionCode]是多少,应用商店就 会以这个[VersionCode]为准,来判断版本。安装包的[VersionCode]数字越大就越新。这样开发者在开发过程中,每有一个新版本只要 加大一点这个数字就可以了。比如第一个版本的[VersionCode]是1,第二个版本是2。因为开发者可能每天可能会产生多个没有发布的版本,所以这 个数字会增长的很快。

经过一段时间的开发,这个数字会变得比较大,比如16385,这时对一个消费者,这样的数字其实不太具有可识别性,比如说Win 16385和Win 17514在传达信息方面效果并不好,不利于产品的市场推广。因此Google也支持在AKP安装包内记录[VersionName],你可以叫Win 7、Win Vista都没问题,可以满足市场、传播方面的需求,这样[VersionName]其实不具备比较新、旧版本的能力,只是用来展示给消费者看的。

综上所述 VersionCode:对消费者不可见,仅用于应用市场、程序内部识别版本,判断新旧等用途。 VersionName:展示给消费者,消费者会通过它认知自己安装的版本。一般我们说的版本号就是这个。

三、我们在运营应用商店的过程中,发现有的开发者会遇到一些问题

1、同一个VersionName(版本号),对应了多个VersionCode 这种情况很常见。 比如说新版本发布之后,某个商店反馈说存在xxx问题,需要修复、定制等等操作,于是商务找工程师出了个新版本,考虑到是小版本升级,版本号没变化,但是VersionCode已经变了。

  • 可能遇到的问题:如果这个新版只在部分商店上线,就会出现都是3.1版,A商店的版本其实比B商店的新。已经安装了新版本的用户,还会被提示升级,这时候用户会困扰,为什么我装了3.1还要升级到3.1?部分商店为了最新会抓包,导致渠道包流窜,影响运营监控和分析。
  •  解决方案:a.版本号应该和VersionCode一起涨,而且一旦发布新版本,就在所有渠道上架新版。

2、发布了一个VersionCode错误的版本 有时候因为工程师不小心,发布了一个VersionCode过大的版本。 比如1.1.1.20版本的VersionCode写成了111,而1.1.1.27版本的VersionCode写成了11127,但是后面发布1.1.2版希望延续旧的VersionCode,用112。

  • 可能遇到的问题:1.1.1.27版的用户将无法获得1.1.2版本的升级,因为在程序看来1.1.1.27版本是比较新的,同时,已经使用了1.1.2版本的用户,可能会收到旧版本的升级提示,比并降级回旧版
  • 解决方案:其实很简单,因为VersionCode对最终用户是不可见的,只要增加就好了,上文的例子,新版VersionCode直接取11200就齐活了。

3、发布了一个有Bug的版本,好捉急 偶尔会遇到版本已经发布了,第二天突然发现,糟糕,有Bug,用户开始骂了!于是商务同学到各家市场要求退回旧版本。

  • 可能遇到的问题:已经升级到有Bug版本的用户是无法回滚到旧版的,因此这样直接退回旧版本的方式对这些热心升级的用户是非常不负责任的。而且人肉召回的力度实在有限,这个有Bug的版本一定会流传的。
  • 解决方案:最好是不要浪费时间退回旧版,赶紧修复Bug发个新版本(记得加VersionCode),如果Bug比较棘手,建议把旧版本的VersionCode改大一些后,提交新版本,这样可以保证所有用户都能下载/升级到一个相对可靠的版本。

什么是包名 (Package Name)?

小米应用商店按照符合Android标准的原则进行设计,使用包名(Package Name)作为应用的唯一标识。即:包名必须唯一,一个包名代表一个应用,不允许两个应用使用同样的包名。包名主要用于系统识别应用,几乎不会被最终用户看到。

包名的命名规则

只能包含大写字母(A到Z)、小写字母(a到z)、数字和下划线,以用点(英文句号)分隔称为断,至少包含2个断,隔开的每一段都必须以字母开头。

避免包名冲突

因为包名是唯一标识,为了避免与其他应用的包名重复,产生冲突,您可以这样命名:

将您的域名反转过来作为前缀,比如如果您的域名是zan.com,那么包名可以用com.zan开头,这样可以有效的避免重复

在后面增加描述产品名称的字符,比如您的应用是视频应用,可以命名为com.zan.video

如果您没有域名,可以使用自己的邮箱作为前缀,比如 com.xiaomi.WoDeYouXiang

包名冲突如何处理?

如果您发现您尚未发布的应用,包名和其他开发者已经发布的应用重复了,建议立刻修改应用的包名,避免冲突。

如果您的应用已经发布了,但是在小米开发者站上传应用时,被告知已经有其他开发者上传了同包名的应用,可以按照指示,进入问题工单系统,联系我们进行处理。

请注意

应用发布后,请不要修改包名,一旦您修改了包名,就会被当作一个新的应用,旧版用户也无法收到应用商店的升级提醒。

VIVO消息推送 接入push服务注意事项

VIVO消息推送 接入push服务注意事项

开发者接入push服务存在的共性问题排查指南:

一、请接入方先通过本地工具【postmen】先调用我们提供的接口,保证本地调用我们的接口是没有问题【减少在开发过程沟通成本】

二、如果是本地工具接口测试:请先检查一下事项

 1、请先测试推送鉴权接口,获取到 authToken 才可以进行消息推送 【可以确保接入方本地调用push服务是通的】

 2、检查一下当前应用是否是受限应用(受限应用将在2-3个工作日内转为正式)

①如果是受限应用,则只能测试单播接口,测试其他推送接口会有对应提示

②如果是受限应用,那么需要在vivo推送营运平台后台添加要测试的设备【设备id(regId)】最多可以添加20个设备

③如果是受限应用,在调用单播接口的时候,需要在请求参数中确认pushMode==1字段(0:正式推送;1:测试推送,不填默认为0)

   测试推送没有频控限制(受限应用发不了正式推送)

3、检查一下当前推送的消息是运营消息还是系统消息【前提:推送为正式推送】

(接入方在推送的时候 参数 classification==0 , 0:运营类消息,1:系统类消息。不填默认为0)

如果客户端多次收到消息后,又出现收不到的情况

检查消息是否被管控,单用户单应用每天收到的消息条数上限5条,系统消息不受应用频控管控,受系统消息推送总量限制

建议:如果只是检验功能,建议使用测试推送【测试消息不受频控、推送量级管控】

三、关于消息数据统计问题【vivo推送运营后台有相关消息统计明细分布情况】

请各个接入方先到 vivo推送管理后台查看当前应用消息大体的数据统计分布情况

统计分两种:

 ①应用级别的消息统计明细分布情况

 ②单推统计明细分布情况

【可以通过这两个指标,进一步分析消息没有达到的原因】    

同时:建议接入方在关键地方也收集数据。比如消息达到客户端,建议应用方也做一个记录。

对我们接口返回的regId(1.userId不存在;2.卸载或者关闭了通知;3.七天不在线;4.非测试用户),这些状态也存储一下,可以预防无效的推送

四、如遇接口返回状态码 10206 sign 不正确提示 【前提:一样的签名方法, 偶现签名不正确】

如果出现这种情况:

就是业务方在进行签名的时候 appId/appKey/appSecret 存在本来给“应用A”生成的签名,结果把sign拿给“应用B”进行签名了

【签名:使用MD5算法,字符串trim后拼接(appId+appKey+timestamp+appSecret),然后通过MD5加密得到的值(字母小写)】

请接入方在有多个应用的时候,要注意签名方法的使用,防止签名误传

五、如遇接口返回状态码 10000 权限认证失败,则表示应用方获取的authToken 失效了 ,请重新获取

六、regId升级

原有token(regId)生成规则是固定23位数字。已不能满足后续增长需求,推送平台从2022年5月开始升级token(regId)生成规则,取消现有固定23位长度及数字限制,新规则长度可变,包含字符“0-9”、“a-z”、“A-Z”及特殊字符。2022年7月30号全量升级。老的regId不变,新订阅会按照新regId规则生成。

七、如何发送测试消息图解

接入Vpush后的应用均可以发送测试消息。发送测试消息的步骤如下:

1、  先在推送运营后台添加测试设备。

1)  在推送平台找到你的应用名称

2)  在刚才的基础之前要点击测试设备

3)  到了这个页面  要点击添加测试设备

4)  添加具体信息点击确定

2、然后接入服务端API,通过调用/message/send,pushMode设置为1,给第一步绑定成功的测试设备发送消息。详情请见《服务端API接口文档》

说明:

1、  添加测试设备为接入客户端SDK,订阅获取到的regId,通过调用客户端api接口的getRegId方法获取,详情请见《客户端API接口文档》

2、最多支持添加20个测试设备

3、测试消息不受量级和频次限制。

VIVO消息推送 Android PUSH-SDK集成指南

点击此处下载 PUSH SDK接入文档(若公司网络下载压缩包解压异常,建议切换其他网络下载)

版本信息具体说明
版本号:484、版本名:3.0.0.4更新内容:
1.优化代码,去掉非必要逻辑;
版本号:483、版本名:3.0.0.3更新内容:
1.修复了读取外部存储的问题;
版本号:482、版本名:3.0.0.2更新内容:
1.恢复了仅用于兼容v3.0.0.0_480以前点击回调接口:onNotificationMessageClicked;
版本号:481、版本名:3.0.0.1更新内容:
1.修复统一推送联盟接口的已知问题;
版本号:480、版本名:3.0.0.0更新内容:
1.修复安全漏洞:通知不再支持拉起非导出的Activity;
2.优化push通知点击启动慢的问题;
3.移除onNotificationMessageClicked回调,自定义参数需要统一在被拉起的Activity中通过Intent接收;

注意:

1.vivo推送服务SDK支持的最低android版本为Android 6.0。

2.当通过”自定义/打开应用页面”方式启动应用内Activity时,该Activity在AndroidManifest.xml必须配置属性android:exported=”true”。

3.由于项目架构变动,可能会导致您在更新sdk版本时类的路径错误,重新导入类的路径即可。

一、集成sdk

1. 导入aar 包

将解压后的libs文件夹中vivopushsdk-VERSION.aar(vivopushsdk-VERSION.aar为集成的jar包名字,VERSION为版本名称)拷贝到您的工程的libs文件夹中。

在android项目app目录下的build.gradle中添加aar依赖。

dependencies {

  implementation fileTree(include: ['*.jar'],   dir: 'libs')

  implementation   files("libs/vivo_pushSDK_v3.0.0.4_484.aar")

}

2. 添加权限

vivo Push集成只需要配置网络权限,请在当前工程AndroidManifest.xml中的manifest节点下添加以下代码:

<!—Vivo Push需要的权限--> 

<uses-permission  android:name="android.permission.INTERNET"/>

3. 配置appid 、api key等信息

vivo Push集成需要配置对应的appid 、app key信息,其中appid 和app key是在开发者平台中申请的,详见 vivo push 操作手册。

请在当前工程AndroidManifest.xml中的Application节点下添加以下代码(建议复制粘贴防止出错):

<!--Vivo Push开放平台中应用的appid 和api key--> 
<meta-data 
   android:name="api_key" 
   android:value="xxxxxxxx"/> 

<meta-data 
   android:name="app_id" 
   android:value="xxxx"/>

4. 自定义通知回调类

在当前工程中新建一个类 PushMessageReceiverImpl(自定义类名)继承OpenClientPushMessageReceiver 并重载实现相关方法。并在当前工程的AndroidManifest.xml文件中,添加自定义Receiver信息,代码如下:

<!--push应用定义消息receiver声明--> 
<receiver android:name="xxx.xxx.xxx.PushMessageReceiverImpl(自定义类名)" 
   android:exported="false">    
<intent-filter> 
	<!--接收push消息--> 
   <action android:name="com.vivo.pushclient.action.RECEIVE"/> 
</intent-filter>
</receiver>

5. 注册service

接入SDK,需注册相关服务以确保正常。

请在当前工程AndroidManifest.xml中的Application节点下添加以下代码(建议复制粘贴防止出错):

<!--Vivo Push需要配置的service、activity--> 
<service 
   android:name="com.vivo.push.sdk.service.CommandClientService" 
   android:permission="com.push.permission.UPSTAGESERVICE"
   android:exported="true"/>

6. 配置sdk版本信息(仅通过jar包集成方式需要配置,通过aar包集成无需配置)

通过jar包方式接入SDK,需配置SDK版本信息确保正常。

请在当前工程AndroidManifest.xml中的Application节点下添加以下代码(建议复制粘贴防止出错):

<!--Vivo Push SDK的版本信息--> 
<meta-data 
   android:name="sdk_version_vivo" 
   android:value="484"/>

二、启动推送

在工程的Application中,添加以下代码,用来启动打开push开关,成功后即可在通知消息到达时收到通知。

//在当前工程入口函数,建议在Application的onCreate函数中,添加以下代码:

//初始化push
PushClient.getInstance(getApplicationContext()).initialize(); 

// 打开push开关, 关闭为turnOffPush,详见api接入文档
PushClient.getInstance(getApplicationContext()).turnOnPush(new IPushActionListener() { 
    @Override
    public void onStateChanged(int state) { 
       // TODO: 开关状态处理, 0代表成功
    } 
});

三、获取token

即获取regId,使用PushClient.getInstance(context).getRegId() 函数获取;

在 Api 接口 turnOnPush回调成功之后,即可获取到注册id。

四、点击通知消息

当设备接收到通知消息后,查看手机的通知栏,当点击通知时,打开通知动作分为打开App首页、打开特定Uri 网址页面、 打开用户自定义、打开应用指定页面。

注意: Sdk 3.0.0.0 以前版本的页面跳转类型打开自定义、打开指定应用页面,在Sdk 3.0.0.0及以后版本中已统一作为打开自定义页面处理。 服务端Api 字段 skipType 跳转类型分别是: 1 是打开App 首页, 2 是打开特定Url 网址页面, 4 是打开自定义页面。

打开App首页或者打开自定义页面,是通过VIVO手机通知中心跨应用启动Activity来实现,需要App保证被拉起的目标Activity exported属性默认设置为true,无权限配置,可以在点击通知时打开指定的Activity。

1. 打开App 首页

在AndroidManifest.xml文件配置主Activity。

在AndroidManifest.xml文件注册的首页Activity 中,配置
<intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
</intent-filter>

在Activity 中接受数据:

开发者在首页的Activity 的onCreate 或者 onNewIntent 中,通过如下方式获取数据。

获取消息id,即messageId:

String messageId = intent.getLongExtra("vivo_push_messageId");

获取透传的自定义键值对值,如下,

遍历所有key(遍历clientCustomMap和skipContent的自定义key-value):

Bundle bundle = intent.getExtras();
if (bundle != null) {
    for (String key : bundle.keySet()) {
        if (!TextUtils.isEmpty(key)) {
            //注意传递的参数类型
            String content = bundle.getString(key);
        }
    }
}

取单个key(取clientCustomMap和skipContent特定key对应的value):

Intent intent = getIntent();
if (intent != null) {
    String key1 = intent.getStringExtra("key1");
    int key2 = intent.getIntExtra("key2", -1);
}
其中key1为用户自定义String型键值对参数值;key2为用户自定义Integer型键值对参数值。

2. 打开自定义页面

注意:原有通过onNotificationMessageClicked回调接收自定义参数的方式已经废弃,自定义参数需要统一在被拉起的Activity中通过Intent接收。

跨应用启动客户端App需要显示启动,通过Intent 携带透传参数到App,生成好对应的 Intent 参数,然后调用服务端Api 指定Intent 参数来打开自定义App页面;

生成 Intent 参数:

在Android 开发工具中,参考如下代码生成 Intent
Intent intent = new Intent(this,CustomActivity.class);
//Scheme协议(vpushscheme://com.vivo.push.notifysdk/detail?)开发者可以自定义
intent.setData(Uri.parse("vpushscheme://com.vivo.push.notifysdk/detail?"));
//intent 中添加自定义键值对,value 为 String 型
intent.putExtra("key1", "xxx"); 
//intent 中添加自定义键值对,value 为 Integer 型
intent.putExtra("key2", xxx);
//得到intent url 值
//示例:intent://com.vivo.pushtest/detail?#Intent;scheme=vpushscheme;component=com.vivo.pushdemo.test/com.vivo.pushsdk.CustomActivity;S.key1=xxx;i.key2=2;end
String intentUri = intent.toUri(Intent.URI_INTENT_SCHEME);
备注 : 开发者以自己实际定义的为准。

注意:在AndroidStudio里生成intentUri后,开发者通过服务端Api或者在管理后台发送通知时,跳转内容(Api 对应字段 为skipContent)透传上例生成的intentUri值,然后在点击通知时打开自定义的 CustomActivity。

在AndroidManifest.xml文件注册被启动的Activity

比如被启动的自定义页面 CustomActivity,其中host、path、scheme 一定要与上面的 Intent 生成参数匹配。

注意:该属性必须设置android:exported=”true”

配置如下:

<activity android:name=".CustomActivity"   
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="com.vivo.push.notifysdk"
            android:path="/detail"
            android:scheme="vpushscheme" />
        </intent-filter>
</activity>

注意: activity 名称用户自己定义.

在自定义的 CustomActivity 中接收数据

如下:

public class CustomActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.xxx);
        //获取通知消息的messagId
        String messageId = intent.getStringExtra("vivo_push_messageId");
        //获取自定义透传参数值
        Intent intent = getIntent();
        if (null != intent) {
            String key1 = intent.getStringExtra("key1");
            int kye2 = intent.getIntExtra("key2", -1);
        }
    }
}

3. 打开特定Uri 网址

开发者通过Api(Api 对应字段 为skipContent)或者管理后台传自己要打开的Url 网址地址即可。

4. 恢复了仅用于兼容v3.0.0.0_480以前点击回调接口:onNotificationMessageClicked

注意Push SDKv3.0.0.2_482特性:该接口仅用于解决v3.0.0.0_480之前的版本升级Push SDK过程中发送的老版本打开自定义通知(skiptype=3)需要依赖点击回调完成跳转时使用,
  新版本通知点击该点击回调是不可用的。

五、混淆说明

若需要混淆app,请在混淆文件中添加以下说明,防止SDK内容被二次混淆,自定义回调类切勿混淆。

-dontwarn com.vivo.push.** 

-keep class com.vivo.push.**{*; } 

-keep class com.vivo.vms.**{*; }

-keep class   xxx.xxx.xxx.PushMessageReceiverImpl{*;}

六、统一推送联盟接入

说明:请完成上述 ‘1.集成SDK’ 和 ‘2.配置信息’ 两个步骤再开始统一推送联盟的接入。

1. 打开push开关

这里只是做了相应的初始化操作,建议用户在自己应用的Application中onCreate()方法中调用turnOnPush操作。

示例代码:

VUpsManager.getInstance().turnOnPush(this, new UPSTurnCallback() {
    @Override
    public void onResult(CodeResult codeResult) {
        if(codeResult.getReturnCode()   == 0){
            Log.d(TAG, "初始化成功");
        }else {
            Log.d(TAG, "初始化失败");
        }
    }
});

2. 注册push

注册push,获取申请的regId,即token。

示例代码:

VUpsManager.getInstance().registerToken(this, "XXX", "XXX", "XXX", new UPSRegisterCallback() {
    @Override
    public void onResult(TokenResult tokenResult) {
        if (tokenResult.getReturnCode() == 0) {
            Log.d(TAG, "注册成功 regID = " +   tokenResult.getToken());
        } else {
            Log.d(TAG, "注册失败");
        }
    }
});

VIVO消息推送 Android PUSH-SDK API接口文档

VIVO消息推送 Android PUSH-SDK API接口文档

点击此处下载 PUSH SDK接入文档

版本号:3.0.0.4

一、 接口概述

本SDK中有两个开放类,分别为:Push操作类PushClient、回调接收类OpenClientPushMessageReceiver/ IPushActionListener。

PushClient 为功能接口,用于调用Push相关功能; 

IPushActionListener 为操作回调接口,用于功能接口状态回调;

OpenClientPushMessageReceiver 为回调接口,用于Push的数据结果返回;

1. PushClient功能类

PushClient提供Push服务的对外API列表,采用单例模型,通过getInstance(Context context)获得该对象。

initialize      初始化Push服务;

checkManifest   检查AndroidManifest是否正确声明组件和权限;

turnOnPush      打开PUSH;

turnOffPush     关闭PUSH;

getRegId        获取当前设备的当前应用的唯一标识;

bindAlias       设置应用别名;

unBindAlias     取消应用别名;

getAlias        获取应用别名;

setTopic        设置主题;

delTopic        删除主题;

getTopics       获取主题;

isSupport       当前系统是否支持PUSH;

2. IPushActionListener操作回调类

IPushActionListener类提供PushClient的操作回调。

onStateChanged  操作状态返回,详见操作码;

3.OpenClientPushMessageReceiver操作回调类

OpenClientPushMessageReceiver类提供基础消息的接收和操作结果的反馈,需要开发者继承本类,并重载相关的方法;同时,还需要在AndroidManifest.xml静态注册。

onReceiveRegId  RegId结果返回,只有首次获取到或regId发生变化时才会回调;

onNotificationMessageClicked  通知被点击时回调(仅用于兼容老版本)。

4. 公共状态码

状态码用于返回各项操作的结果,常用于回调接收类中状态返回,以下为公共状态码:

0       操作成功;

1       操作成功,此动作在未操作前已经设置成功;

101     系统不支持;

102     PUSH初始化异常,请重现初始化PUSH;

1001    一天内调用次数超标;

1002    操作频率过快;

1003    操作超时;

1004    应用处于黑名单;

1005    当前push服务不可用;

10000   未知异常;

10001   topic错误,例如传入appid/;

10002   topic错误, 例如appid/null;

10003   app包名与配置不匹配,例如传入com.yyy;

10004   appkey不匹配,例如传入appkey:bcd不存在;

10005   appid传入错误,例如未申请此appid,传入111;

10006   别名长度超过40;

10007   别名订阅时appkey不存在;

10008   开放平台暂不支持tag订阅;

二、 API接口

PushClient类

① Initialize

功能介绍:初始化push服务,可以提高后台发送消息的实时性。

接口定义:void initialize();

补充:建议每次手机启动后,都调用一次,确保Push服务能够正常运行。

② turnOnPush

功能介绍:打开应用push开关,绑定应用,成功后便可接收到当前应用的推送消息。

接口定义:void turnOnPush(IPushActionListener listener);

参数说明:listener: 状态监听;

补充:打开push成功后无需重复调用。

③ turnOffPush

功能介绍:关闭应用push开关,解除绑定应用,解绑后将收不到当前应用的推送消息。

接口定义:void turnOffPush(IPushActionListener listener);

参数说明:listener: 状态监听;

补充:关闭push成功后无需重复调用。

④ getRegId

功能介绍: 获取当前设备的当前应用的唯一标识,后台可基于此标识发送通知。

接口定义:String getRegId();

返回值:当前设备的当前应用的唯一标识;

补充:此方法仅在打开PUSH成功后可以获取,否则为null。

⑤ bindAlias

功能介绍:在注册成功,收到regId之后,即可设置别名,绑定当前设备的当前应用的别名,可以理解为regId的别名,开发者可以将别名设置为自己应用帐号系统的帐号,或者设备标识等。然后通过此别名发送消息。

接口定义:bindAlias(String alias, IPushActionListener listener);

参数说明:alias:别名; listener: 状态监听。

**状态码 描述**

30001   设置别名失败:请打开push开关;

30002   设置别名失败:订阅别名为空;

30003   设置别名失败:别名设置超长,字符长度超过70;

补充:绑定别名,同一个别名仅能绑定一个regId。当regId已绑定了别名A,若调用此接口绑定别名B,则与别名A的绑定关系会自动解除。此接口与 unBindAlias 一天内最多调用100次,两次调用的间隔需大于2s。

⑥ unBindAlias

功能介绍:删除别名,解除绑定当前应用别名,解绑成功后后台将无法通过别名的方式向应用发消息。

接口定义:

void unBindAlias(String alias);
void unBindAlias(String alias, IPushActionListener listener);

参数说明: alias:别名; listener:状态监听。

**状态码 描述**

30001   删除别名失败:请打开push开关;

30002   删除别名失败:订阅别名为空;

30003   删除别名失败:别名设置超长,字符长度超过70;

补充:此接口与 bindAlias 一天内最多调用100次,两次调用的间隔需大于2s。

⑦ getAlias

功能介绍:获取当前设备的应用别名,后台可基于此别名发送通知。

接口定义:String getAlias();

返回值:当前设备的应用别名。

⑧ checkManifest

功能介绍:校验接入是否异常。通过调用该API来检查AndroidManifest.xml是否正确声明了本SDK要求的所有组件和权限。当有组件和权限未定义,或者组件的属性声明错误时抛出异常VivoPushException。

接口定义:void checkManifest()。

⑨ setTopic

功能介绍:在注册成功,收到regId之后,即可设置主题;开发者可根据用户订阅的主题实现分组。

接口定义:setTopic(String topic, IPushActionListener listener);

参数说明:topic : 需要订阅的主题名; listener : 状态监听。

**状态码 描述**

20001   设置主题失败:请打开push开关;

20002   设置主题失败:订阅主题为空;

20003   设置主题失败:别名设置超长,字符长度超过70;

20004   设置主题失败:订阅次数太频繁或已订阅数过多;

补充:同一个regId可设置多个主题,最多可订阅500个主题。当regId已设置了topicA,若调用此接口设置topicB,则regId同时订阅了topicA和topicB。此接口与 delTopic 一天内最多调用500次,两次调用的间隔需大于2s。

⑩ delTopic

功能介绍:删除已经设置的主题。

接口定义:delTopic(String topic, IPushActionListener listener);

参数说明:topic 需要取消订阅的主题名; listener 状态监听。

**状态码 描述**

20001   设置主题失败:请打开push开关;

20002   设置主题失败:订阅主题为空;

20003   设置主题失败:别名设置超长,字符长度超过70;

20004   设置主题失败:订阅次数太频繁或已订阅数过多;

补充:此接口与 setTopic 一天内最多调用500次,两次调用的间隔需大于2s。

⑪ getTopics

功能介绍:获取当前设备的应用主题,后台可基于此主题发送通知。

接口定义:List getTopics();

返回值:当前设备已经设置的应用主题;

⑫ isSupport

功能介绍:用于判断当前系统是否支持PUSH服务。

接口定义:boolean isSupport();

返回值:true 系统支持; false 系统不支持。

⑬ onReceiveRegId

功能介绍:RegId结果返回。当开发者首次调用turnOnPush成功或regId发生改变时会回调该方法。

接口定义:void onReceiveRegId(Context context, String regId);

参数说明:context : 应用上下文; regId: 当前设备的当前应用的唯一标识;

⑭ onNotificationMessageClicked(仅用于兼容老版本)

功能介绍:通知被点击后的结果返回。当push发出的通知被点击后便会触发onNotificationClicked通知应用。

接口定义:void onNotificationMessageClicked(Context context, UPSNotificationMessage msg);

参数说明:context : 应用上下文; msg: UPSNotificationMessage通知消息结构体;

**UPSNotificationMessage 包含以下字段**
msgId:通知id。
title:通知标题。
content:通知内容。
skipContent:通知自定义内容。
params:自定义键值对。

三、统一推送联盟API介绍

① turnOnPush

功能介绍:做了相应的初始化操作,建议用户在自己应用的Application中的onCreate()方法中调用turnOnPush操作。

接口定义:

void turnOnPush(Context context, UPSTurnCallback callback)

参数说明:

context : 应用上下文;

Callback:UPSTurnCallback 回调结构,包含以下方法;

 .getReturnCode()  获取返回状态,0代表成功,其他值代表失败。

② registerToken

功能介绍:注册push,获取申请的regId

接口定义:

void registerToken(final Context context, String appID, String appKey, String appSecret, final UPSRegisterCallback callback)

参数说明:

context : 应用上下文;

appID: 应用在Vivo开放平台申请的APPId;

appKey: 应用在Vivo开放平台申请的APPKey;

appSecret: 应用在Vivo开放平台申请的APPSecret;

callback: UPSRegisterCallback回调结构,包含以下方法;

 .getReturnCode() 获取返回状态,0代表成功,其他值代表失败;

 .getToken()  获取应用申请的regId。

③ unRegisterToken

功能介绍:接注册push,关闭push功能

接口定义:

void unRegisterToken(Context context, final UPSRegisterCallback callback)

参数说明:

context : 应用上下文;

Callback:UPSRegisterCallback回调结构,包含以下方法;

.getReturnCode():获取返回状态,0代表成功,其他值代表失败。

④ turnOffPush

功能介绍:该功能暂时未具体实现,要关闭push功能,请调用上面的unRegisterToken接口

接口定义:

void turnOffPush(Context context, final UPSTurnCallback callback)

参数说明:

context : 应用上下文;

Callback:UPSTurnCallback回调结构,包含以下方法;

.getReturnCode():获取返回状态,0代表成功,其他值代表失败。

VIVO消息推送服务端SDK文档

VIVO消息推送服务端SDK文档

点击此处下载PUSH-JAVA-SDK 文档

版本:2.3 

升级内容:

      1.  新增推必安审核参数auditReview。

      2.  取消regId23位校验限制。

点击此处下载push-python3-SDK 文档

版本:2.2

一、接入SDK

1.运行环境

该SDK使用Java编写,接入前请确认是否安装Java环境,并在Java环境下运行。

2.获取SDK并导入

开发者需要注册登录开发平台网站获取应用的appId,appKey,appSecret;

在开发者网站上,下载并解压vivoPush_sdk_JAVA.zip;

将文件夹下所有jar文件放入项目工程的libs目录;

刷新工程,确保文件出现在libs目录下。如果没有的话请手动添加;

3.示例:给测试手机发送一条单推

集成sdk后运行该main函数,标红部分为需要使用者填写的内容。运行成功后设备会收到推送(需提前确认设备通知栏权限已打开)

public   static void main(String[] args) throws Exception {
      Sender sender = new Sender(“appSecret”);//注册登录开发平台网站获取到的appSecret
      Result result = sender.getToken(appId ,   “appKey”);//注册登录开发平台网站获取到的appId和appKey
      sender.setAuthToken(result. getAuthToken());
      Message singleMessage = new Message.Builder()
              //该测试手机设备订阅推送所得的regid,且已添加为测试设备.regId(“regId”)              .notifyType(3)
                .title(“try_title”)
                .content(“try-content”)
              .timeToLive(1000)
                .skipType(2)
                .skipContent(“http://www.vivo.com”)
                .networkType(-1)
                .requestId(“1234567890123456”)              .pushMode(1)              .build();
      Result resultMessage = sender.sendSingle(singleMessage);
      System.out.println(resultMessage);
  }

4.SDK类定义说明

类名使用说明
Message消息对象
Builder构建要发送的Message对象
TargetMessage构建批量推送的发送目标
TagMessage标签相关的消息体
TagGroupMessage标签分类的消息体
TagSegMessage标签组合相关的消息体
Sender发送消息工具类,可以发送鉴权、单推、批量推、全推、标签推消息
TagManage创建标签工具类,用于创建,更新标签
TagGroup标签分类管理工具类,用于创建,更新标签分类
TagSegment标签组合管理工具类,用于创建,更新标签组合
Result服务器返回的结果
Validation对构建的消息体进行基本参数校验
ExceptionStatusEnum消息体参数错误类型

二、发送消息

①发送消息依赖Sender类

com.vivo.push.sdk.server.Sender

标签相关的设置依赖以下三个类

com.vivo.push.sdk.server.TagManage

com.vivo.push.sdk.server.TagGroup

com.vivo.push.sdk.server.TagSegment

②实例化Sender

Sender(String appSecret),(鉴权时使用)appSecret是在开发者网站上注册时生成的。

sender.setAuthToken(String authToken);,(推送时使用)除鉴权方法外,推送前都需要设置authToken,authToken是在调用鉴权方法后获得。

③设定连接池参数(可选项)

Sender.initPool(int connection, int route) 设定连接池最大连接数为“connection”,路由最大连接数为“route”,不设定该项则使用默认参数:最大连接数 10,路由最大连接数 5

④返回结果Result

com.vivo.push.sdk.server.Result

1.鉴权

要进行PUSH推送,任何接入方都要有个鉴权操作。获得authToken用于各类推送。

限制:一天限制调用不超过10000次。

接口说明:

com.vivo.push.sdk.server.Sender

方法说明
getToken(int   appId,String appKey)根据appId,appKey(用户申请推送业务时生成)进行鉴权操作。

Demo

public void testGetToken() throws Exception   {          Sender sender = new     Sender(APP_SECRET);//实例化Sender              sender.initPool(20,10);//设置连接池参数,可选项          Result result =   sender.getToken(APP_ID,APP_KEY);//发送鉴权请求            result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述              result.getAuthToken();//如鉴权请求发送成功,获得authToken    }

2.单推

接入方携带消息内容以及用户regId(或alias:别名)进行通知消息推送。针对每个用户发送不同的通知。

使用场景:如物流、订单状态、游戏预约状态、行程状态、聊天(如微信、评论)等。

接口说明:

com.vivo.push.sdk.server.Sender

方法说明
sendSingle(Message   singleMessage)根据消息体singleMessage中设定的regId或alias发送消息到指定设备上。

Demo

public   void singeSend() throws Exception {          Sender sender = new     Sender(APP_SECRET);sender.initPool(20,10);//设置连接池参数,可选项sender.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          Message singleMessage     = new Message.Builder().~.build();//构建单推消息体          Result result =     sender.sendSingle(singleMessage);//发送单推请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述          result.getTaskId();//如单推请求发送成功,将获得该条单推消息的任务编号,即taskId          result. getInvalidUser();//非法用户信息,包括status和userid          result.   getInvalidUser().getStatus();//非法用户信息状态,包括四种情况, 1 userId不存在。 2卸载或者关闭了通知。 3 14天不在线。4 非测试用户          result.   getInvalidUser().getUserid();//非法的用户信息,即接入方传的regid或者alias      }

3.批量推送

3.1保存群推消息

同一条信息覆盖多个用户。此方法需与批量推送用户方法2.3.2配套使用,批量推送用此方法返回的taskId批量发送用户。

使用场景:活动、系统升级提醒等。

接口说明:

com.vivo.push.sdk.server.Sender

方法说明
saveListPayLoad(Message   listPayLoad)把构建的消息体listPayLoad发送保存至服务器上,返回该消息的taskId

Demo

public void saveListPayload()   throws   Exception {          Sender sender = new   Sender(APP_SECRET);sender.initPool(20,10);//设置连接池参数,可选项sender.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          Message saveList =   new   Message.Builder().~.build();//构建要保存的批量推送消息体          Result result =     sender. saveListPayLoad(saveList);//发送保存群推消息请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述          result.getTaskId();//如请求发送成功,将获得该条消息的任务编号,即taskId    }

3.2批量推送用户

批量发送给用户。该方法与保存群推消息方法2.3.1配套使用,首先通过2.3.1获得taskId,然后使用该taskId,根据regIds或者aliases进行批量推送。

接口说明:

com.vivo.push.sdk.server.Sender

方法说明
sendToList(TargetMessage   targetMessage)把某条消息批量发送给多个用户

Demo

public   void listSend() throws Exception {          Sender sender = new     Sender(APP_SECRET);              sender.initPool(20,10);//设置连接池参数,可选项sender.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          Set<String>     regid = new HashSet<>();//构建批量推送用户群          regid.add(taskId1);          regid.add(taskId2);          …          TargetMessage     targetMessage = new   TargetMessage.Builder().~.build();//构建批量推送的消息体          Result result =     sender.sendToList(targetMessage);//批量推送给用户result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述          result. getInvalidUsers();//非法用户信息列表,其中每个非法用户信息包括status和userid两个属性,userid为接入方传的regid或者alias,status有四种情况:1 userId不存在 2卸载或者关闭了通知 3 14天不在线 4非测试用户      }

4.全量推送

向所有设备推送某条消息。

使用场景:活动、系统升级提醒等。

接口说明:

com.vivo.push.sdk.server.Sender

方法说明
sendToAll(Message   allMessage)把构建的消息allMessage发送给所有设备

Demo

public void allSend() throws     Exception {          Sender sender = new     Sender(APP_SECRET);              sender.initPool(20,10);//设置连接池参数,可选项sender.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          Message allSendMessage     = new Message.Builder().~.build();//构建要全量推送的消息体          Result result =     sender. sendToAll(allSendMessage);//发送全量推送消息请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述          result.getTaskId();//如请求发送成功,将获得该条消息的任务编号,即taskId    }

5.标签推

接入方携带消息内容、标签信息进行通知消息推送。根据标签把消息推送给指定用户

接口说明:

com.vivo.push.sdk.server.Sender

方法说明
sendToTag(Message   tagMessage)把构建的消息发送给标签圈定的用户

Demo

public void tagSend() throws Exception     {          Sender sender = new   Sender(APP_SECRET);              sender.initPool(20,10);//设置连接池参数,可选项sender.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          Message   tagSendMessage   = new Message.Builder().~.build();//构建要全量推送的消息体          Result result =     sender. sendToTag(tagSendMessage);//发送标签推送消息请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述          result.getTaskId();//如请求发送成功,将获得该条消息的任务编号,即taskId    }

6.消息体创建

6.1通知栏消息体

com.vivo.push.sdk.server.Message.Builder

Builder方法列表

方法说明
Builder()构造方法
regId(String value)仅单推时需设定(其它推送无需设定该项),单推可通过regId推送给指定用户。应用订阅PUSH服务器得到的id ,长度23个字符(regId,alias 两者需一个不为空,当两个不为空时,取regId)
alias(String value)仅单推时需设定(其它推送无需设定该项),单推可通过alias推送给指定用户。应用订阅PUSH服务器别名,长度不超过40字符(regId,alias 两者需一个不为空,当两个不为空时,取regId)
orTagss(List<String> valus)仅标签推送时需设定(其他推送无需设定该项),标签表达式包含三种数组: notTags表示非操作、andTags表示与操作,orTagss表示或操作,例如:                     “notTags”:[“琴”,”棋”,”书”,”画”],                      “andTags”:[“深圳”,”广东”],                      “orTagss”:[“本科生”,”研究生”]可以表示为,不会琴、棋、书、画的广东省深圳市的本科生或研究生的所有用户。这些标签需要先在平台,接口,或调用该说明文档3部分的方法,创建相应标签后再使用。具体使用方式可参考下面的DEMO和文档5.3部分
andTags(List<String> valus)
notTags(List<String> valus)
title(String value)必填项,设置通知标题(用于通知栏消息),最大20个汉字(一个汉字等于两个英文字符,即最大不超过40个英文字符)
content(String value)必填项,设置通知内容(用于通知栏消息)   最大50个汉字(一个汉字等于两个英文字符,即最大不超过100个英文字符)
notifyType(int value)必填项,设置通知类型,value类型支持以下值:1:无2:响铃3:振动4:响铃和振动
timeToLive(int value)可选项, 消息的生命周期, 若用户离线, 设置消息在服务器保存的时间, 单位: 秒默认时间:1天最长时间:7天最少时间:单推,60秒         其它,900秒
skipType(int value)必填项,设置点击跳转类型,value类型支持以下值:1:打开APP首页2:打开链接3:自定义4:打开app内指定页面
skipContent(String value)可选项,跳转内容跳转类型为2时,跳转内容最大1000个字符,跳转类型为3或4时,跳转内容最大1024个字符
networkType(int value)可选项,发送推送使用的网络方式,value支持以下值:-1:方式不限1:仅在wifi下发送不填默认为-1
clientCustomMap(String key, String         value)可选项,客户端自定义键值对,自定义key和value键值对个数不能超过10个,且长度不能超过1024字符,   key和value键值对总长度不能超过1024字符。
extra(String callback, String param)可选项,仅单推中使用,提供了高级特性(消息送达回执)。callback参数:不能为null,是第三方接收回执的http接口,最大长度128个字符,vivo推送服务器将已送达或和设备对应的alias或者regId通过调用第三方设置的回调http接口传给开发者服务器。param参数:可以为null,第三方自定义回执参数,最大长度64个字符
requestId(String value)必填项,用户请求唯一标识 最大64字符
classification(int value)消息类型 0:运营类消息,1:系统类消息
pushMode(int   value)推送模式 0:正式推送;1:测试推送,不填默认为0(测试推送,只能给web界面录入的测试用户推送;审核中应用,只能用测试推送)
build()根据设置的属性, 生成Message对象

Demo

public Message buildMessage() throws     Exception {            List<String> andTags = new ArrayList<>();            andTags.add(“TAG1”);            List<String> orTagss = new ArrayList<>();            orTags.add(“TAG2”);            List<String> notTags = new ArrayList<>();            notTags.add(“TAG3”);            Message message = new Message.Builder()                    .regId(“12345678901234567890123”)//仅构建单推消息体需要                  .alias(ALIAS) //仅构建单推消息体需要                  .orTagss(orTagss)     //仅构建标签推消息体需要                  .andTags(andTags)//仅构建标签推消息体需要                  .notTags(notTags) //仅构建标签推消息体需要                  .notifyType(1)                    .title(“YOUR_TITLE”)                    .content(“YOUR_CONTENT”)                  .timeToLive(1000)                  .skipType(2)                    .skipContent(“http://www.vivo.com”)                  .networkType(-1)                    .clientCustomMap(“key1”, “value1”)                    .extra(“http://www.vivo.com”, “vivo”)                    .requestId(“1234567890123456”)                  .classification(1).build();          Return message;    }
6.2批量推送用户消息体

com.vivo.push.sdk.server.TargetMessage.Builder

Builder方法列表

方法说明
Builder()构造方法
regIds(Set<String> regIds)regId列表,个数大于等于2,小于等于1000,regId长度23个字符(regIds,aliases 两者需一个不为空,两个都不为空时,取regIds)
aliases(Set<String> aliases)别名列表,个数大于等于2,小于等于1000,长度不超过40字符(regIds,aliases 两者需一个不为空,两个都不为空时,取regIds)
taskId(String taskId)必填项,公共消息任务号,即调用com.vivo.push.sdk.server.Sender.saveListPayLoad返回的taskId
requestId(String requestId)必填项,用户请求唯一标识   最大64字符
build()根据设置的属性, 生成TargetMessage对象

Demo

public TargetMessage buildTargetMessage()     throws Exception {          Set<String>     regids = new HashSet<>();              regids.add(“12345678901234567890123”);            regids.add(“12345678901234567890321”);          Set<String>     aliases = new HashSet<>();              aliases.add(“ALIAS1”);              aliases.add(“ALIAS2”);          TargetMessage     targetMessage = new TargetMessage.Builder()                      .regIds(regids)                      .aliases(aliases)                      .requestId(“1234567890123456”)                      .taskId(“123456789012345678”).build();          Return targetMessage;    }

7.获取消息推送的统计值

获取批量推送或全量推送返回的taskId对应的统计信息,单次查询的taskIds最多100个。

接口说明:

com.vivo.push.sdk.server.Sender

方法说明
getStatistics(Set<String>     taskIds)查询taskIds里面所有taskId对应的统计信息,taskIds里最多存放100个taskId

Demo

public void testGetStatistics() throws   IOException {          Sender sender = new     Sender(APP_SECRET,authToken);              sender.initPool(20,10);//设置连接池参数,可选项          Set<String>     taskIds = new HashSet<>();              taskIds.add(“123456789012345678”);              taskIds.add(“123456789087654321”);          Result result =     sender.getStatistics(taskIds);result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述          result. getStatistics     ();//如请求发送成功,将获得各个taskId对应的统计数据    }

三、标签管理

1.新增标签

为应用方增加标签,用于后续标签推送。

接口说明:

com.vivo.push.sdk.server.TagMange

方法说明
addTag(TagMessage   tagMessage)根据消息体tagMessage中设定的相关信息创建新标签。

Demo

public void tagAdd() throws Exception {        TagManage   tagManage   =   new TagManage (APP_SECRET);tagManage.initPool(20,10);//设置连接池参数,可选项tagManage.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          TagMessage tagMessage = new     TagMessage.Builder()                      .name(“TAG_NAME”) //必填项,标签名称                      .desc(“TAG_DESCRIPTION”)//可选项,标签描述                    .group(“GROUP_NAME”)//可选项,标签分类名称(参考4部分)                    .build(); //构建创建标签的消息体          Result result =   tagManage.addTag(tagMessage);//发送创建标签请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述}

2.更新单个标签

更新一个标签的信息,更新标签名字、描述、所属分类。

接口说明:

com.vivo.push.sdk.server.TagMange

方法说明
updateTag (TagMessage   tagMessage)根据消息体tagMessage中设定的相关信息更新已存在的标签信息。

Demo

public void tagUpdate() throws Exception {          TagManage tagManage   =   new TagManage (APP_SECRET);tagManage.initPool(20,10);//设置连接池参数,可选项tagManage.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          TagMessage tagMessage = new     TagMessage.Builder()                      .oldName(“OLD_NAME”)//必填项,旧的标签名称                      .newName(“NEW_NAME”)//必填项,新的标签名称                      .desc(“TAG_DESCRIPTION”)//可选项,更新标签描述                    .group(“GROUP_NAME”)//可选项,更新标签分类(参考4部分)                    .build(); //构建更新标签的消息体        Result   result =   tagManage.updateTag(tagMessage);//发送更新标签请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述}

3.给标签添加用户设备

给标签添加用户设备信息,单次不超过1000个设备。

接口说明:

com.vivo.push.sdk.server.TagMange

方法说明
addMembers(TagMessage   tagMessage)把tagMessage中指定的用户设备添加到指定的标签中。

Demo

public void tagAddMembers () throws   Exception {          TagManage tagManage   =   new TagManage (APP_SECRET);tagManage.initPool(20,10);//设置连接池参数,可选项tagManage.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)Set<String>   ids = new   HashSet<>();ids.add(“REGID1”);ids.add(“REGID2”);          TagMessage tagMessage     = new TagMessage.Builder()                      .name(“TAG_NAME”)//必填项,要添加用户设备的标签名称                    .type(1)// 必填项,用户类型:1是regId ,2是别名                    .ids(ids)//必填项,用户id                    .build();//构建给标签添加用户设备的消息体          Result result =   tagManage.addMembers   (tagMessage);//发送给标签添加用户设备的请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述        result.getData();//非法用户信息列表,其中每个非法用户信息包括status和userid两个属性,userid为接入方传的regid或者alias,status有三种情况:1是用户不存在,2是用户push开关关闭,3是用户14天未联网}

4.移除标签中的用户设备

移除标签中的用户设备信息,单次不超过1000个设备。

接口说明:

com.vivo.push.sdk.server.TagMange

方法说明
removeMembers(TagMessage   tagMessage)把tagMessage中指定的用户设备从指定标签中移除。

Demo

public void tagRemoveMembers () throws   Exception {          TagManage tagManage   =   new TagManage (APP_SECRET);tagManage.initPool(20,10);//设置连接池参数,可选项tagManage.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)Set<String>   ids = new   HashSet<>();ids.add(“REGID1”);ids.add(“REGID2”);          TagMessage   tagMessage   = new TagMessage.Builder()                    .name(“TAG_NAME”)//必填项,要移除用户设备的标签名称                    .type(1)// 必填项,用户类型:1是regId ,2是别名                    .ids(ids)//必填项,用户id                    .build();//构建移除标签用户设备的消息体          Result result = tagManage.     addMembers (tagMessage);//发送移除标签中的指定用户设备的请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述          result.getData();//非法用户信息列表,其中每个非法用户信息包括status和userid两个属性,userid为接入方传的regid或者alias,status有三种情况:1是用户不存在,2是用户push开关关闭,3是用户14天未联网}

四、标签分类管理

1.新增标签分类

为应用方增加标签分类,用于后续标签分类管理。

接口说明:

com.vivo.push.sdk.server.TagGroup

方法说明
addTagGroup(TagGroupMessage     groupMessage)根据消息体groupMessage中设定的相关信息创建新标签分类。

Demo

public void addGroup() throws Exception {          TagGroup tagGroup =     new TagGroup (APP_SECRET);tagGroup.initPool(20,10);//设置连接池参数,可选项tagGroup.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          TagGroupMessage   groupMessage   = new TagGroupMessage.Builder()                      .name(“GROUP_NAME”)//必填项,标签分类名称                    .type(1)//必填项,标签分类类型:1是普通标签,2是互斥标签                      .desc(“one group”)//可选项,标签分类的描述信息                    .build();//构建新增标签分类的消息体       Result result   = tagGroup.addTagGroup   (groupMessage);//发送创建标签分类的请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述}

2.更新单个标签分类

更新一个标签分类的信息,包括标签分类名称和描述。

接口说明:

com.vivo.push.sdk.server.TagGroup

方法说明
updateTag(TagGroupMessage     groupMessage)根据消息体groupMessag中设定的相关信息更新已存在的标签分类信息。

Demo

public void updateGroup() throws Exception {          TagGroup tagGroup =     new TagGroup (APP_SECRET);tagGroup.initPool(20,10);//设置连接池参数,可选项tagGroup.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          TagGroupMessage     groupMessage = new TagGroupMessage.Builder()                      .oldName(“OLD_NAME”)//必填项,旧的标签分类名称                      .newName(“NEW_NAME”)//必填项,新的标签分类名称                      .desc(“TAG_DESCRIPTION”)//可选项,更新标签分类的描述                    .build(); //构建更新标签分类的消息体          Result result =   tagGroup.updateTagGroup   (groupMessage);//发送更新标签分类的请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述}

3.添加标签到标签分类中

把标签添加进标签分类里面,一次可添加一个或者多个标签,最多不超过100个。

接口说明:

com.vivo.push.sdk.server.TagGroup

方法说明
addTagToGroup(TagGroupMessage groupMessage)把groupMessag中指定的标签添加到指定的标签分类中。

Demo

public void tagsToGroup() throws Exception {          TagGroup tagGroup =     new TagGroup (APP_SECRET);tagGroup.initPool(20,10);//设置连接池参数,可选项tagGroup.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)List<String>   tagList = new   ArrayList<>();tagList.add(“TAG1”);tagList.add(“TAG2”);          TagGroupMessage     groupMessage = new TagGroupMessage.Builder()                    .name(“TAG_GROUP_NAME”)//必填项,需添加标签的标签分类名称                    .tagList(tagList)//必填项,标签列表                    .build(); //构建添加标签到标签分类的消息体          Result result =   tagGroup.addTagToGroup   (groupMessage);//发送添加标签到标签分类的请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述}

五、标签组合管理

1.新增标签组合

为应用方增加标签组合。 一个标签组合由多个标签组成。

接口说明:

com.vivo.push.sdk.server.TagSegment

方法说明
addTagSegment(TagSegMessage segMessage)根据消息体segMessage中设定的相关信息创建新标签组合。

Demo

public void addSegment() throws Exception {          TagSegment   tagSegment   = new TagSegment (APP_SECRET);tagSegment.initPool(20,10);//设置连接池参数,可选项tagSegment.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          List<String> andTags     = new ArrayList<>();            andTags.add(“TAG1”);          List<String> orTagss     = new ArrayList<>();          orTags.add(“TAG2”);          List<String> notTags     = new ArrayList<>();            notTags.add(“TAG3”);          TagSegMessage     segMessage = new TagSegMessage.Builder()                    .name(“SEGMENT_NAME”)//必填项,标签组合的名称                    .andTags(andTags)//与操作                    .orTagss(orTags)//或操作                    .notTags(notTags)//非操作(具体与,或,非含义,操作参考5.3)                    .build();//构建新增标签组合的消息体      Result result   =   tagSegment.addTagSegment (segMessage);//发送创建标签组合的请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述}

2.更新标签组合

更新一个标签组合的信息。

接口说明:

com.vivo.push.sdk.server.TagSegment

方法说明
addTagSegment(TagSegMessage     segMessage)根据消息体segMessage中设定的相关信息创建新标签组合。

Demo

public void updateSegment() throws Exception   {          TagSegment   tagSegment   = new TagSegment (APP_SECRET);tagSegment.initPool(20,10);//设置连接池参数,可选项tagSegment.setAuthToken(authToken);//设置推送的必要参数authToken(调用鉴权方法获得)          List<String> andTags     = new ArrayList<>();            andTags.add(“TAG1”);          List<String> orTagss     = new ArrayList<>();            orTagss.add(“TAG2”);          List<String> notTags     = new ArrayList<>();            notTags.add(“TAG3”);          TagSegMessage     segMessage = new TagSegMessage.Builder()                      .oldName(“OLD_NAME”)//必填项,旧的标签组合名称                    .newName(“NEW_NAME”)//必填项,新的标签组合名称                    .andTags(andTags)//与操作                    .orTagss(orTags)//或操作                    .notTags(notTags)//非操作(具体与,或,非含义,操作参考5.3)                    .build();//构建新增标签组合的消息体      Result result   =   tagSegment.updateTagSegment (segMessage);//发送更新标签组合的请求result.getResult();//获取服务器返回的状态码,0成功,非0失败          result.getDesc();//获取服务器返回的调用情况文字描述}

3.标签组合表达式

List<String> andTags = new   ArrayList<>();andTags.add(“深圳”,”广东”);List<String> orTagss = new   ArrayList<>();orTagss.add(“本科生”,”研究生”);List<String> notTags = new   ArrayList<>();notTags.add(“琴”,”棋”,”书”,”画”);TagSegMessage segMessage = new   TagSegMessage.Builder()                      .name(“SEGMENT_NAME”)//必填项,标签组合的名称                    .andTags(andTags)//与操作                    .orTagss(orTags)//或操作                    .notTags(notTags)//非操作                    .build();
标签表达式包含三种数组: notTags表示非操作、andTags表示与操作,orTagss表示或操作,例如如上面所示创建标签表达式,即代表:                 “notTags”:[“琴”,”棋”,”书”,”画”],                  “andTags”:[“深圳”,”广东”],                  “orTagss”:[“本科生”,”研究生”]可以表示为,不会琴、棋、书、画的广东省深圳市的本科生或研究生的所有用户。这些标签需要先在平台,接口,或调用该说明文档3部分的方法,创建相应标签后再使用。

VIVO消息推送服务端API接口文档

VIVO消息推送服务端API接口文档

当前版本:2.9.2

修改记录:

(1)/message/auth接口,鉴权码生成方式优化,增加调用频率为10次/s,取消每天10000次数量限制;

(2)各接口请求体,新增appId,用于跟鉴权信息进行比对,确认是否为应用信息一致,不一致返回错误码10094

一.公共

1.推送超量说明

如果调用接口出现超量限制的返回码,请不要在当天高频次调用服务器相应接口,否则将调低推送量级;

出现“10070:发送总量超出限制”。当天不要调用/message/send 单推接口;

出现“10252:批量发送消息体超出限制”。当天不要调用/message/saveListPayload 保存群推消息公共体接口;

出现“10070:发送总量超出限制”。当天不要调用/message/saveListPayload 保存群推消息公共体接口,以及/message/pushToList 批量推送用户接口;

出现“10254:全量发送超过次数限”。当天不要调用/message/all 全量发送接口;

关于推送量的说明可以参考【vivo推送常见问题汇总】

2.vivo服务器地址

https://api-push.vivo.com.cn

3.公共传入参数

HTTP Header中(推送鉴权接口除外)。

属性名字类型是否必填Y/N描述
authTokenstringY当鉴权成功时会返回该字段,推送消息时需要提供authToken,有效期默认为1天,过期后无法使用

4.高级特性extra

注意:回执目前仅支持单推接口且是正式消息 

属性名字类型是否必填Y/N描述
callbackstringY第三方接收回执的http接口,最大长度128个字符
callback.paramstringN第三方自定义回执参数,最大长度64个字符

二.接口定义

1.鉴权

1.1推送鉴权接口

接口说明

要想调用PUSH接口,任何接入方都要有个鉴权操作。其他接口header中必须携带该参数。

接口返回的参数authToken,一个appId可对应多个token,24小时过期,业务方做中心缓存,1-2小时更新一次。

限制:频率限制,单个app 10次/s。超频返回错误码10094。

访问方式

URL编码方式协议methodContent-Type
/message/authUtf-8httpsPOSTapplication/json
Curl e.g.:curl -X POST -H     ‘Content-Type:application/json’ -d   ‘${your_request_body}’     https://api-push.vivo.com.cn/message/authRequest body e.g.:{        “appId”:10004,          “appKey”:”25509283-3767-4b9e-83fe-b6e55ac6243e”,        “timestamp”:1501484120000,          “sign”:”8424f52fd5eaedc16474e4f702d230d2″}Response body e.g.:http status 200:业务成功:{         “result”:   0,         “desc”:   “请求成功”,        “authToken”:     “24ojds98fu3jqrioeu982134jieds9fq43u09uaf”}业务异常:{         “result”:   xxx,         “desc”:   “xxx不合法”}http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId
appKeystringY用户申请推送业务时获得的appKey
timestamplongYUnix时间戳 做签名用,单位:毫秒,且在vivo服务器当前utc时间戳前后十分钟区间内。
signstringY签名 使用MD5算法,字符串trim后拼接(appId+appKey+timestamp+appSecret),然后通过MD5加密得到的值(字母小写)

 输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
authTokenstring当鉴权成功时才会有该字段,推送消息时,需要提供authToken,有效期默认为1天,过期后无法使用。一个appId可对应多个token,24小时过期,业务方做中心缓存,1-2小时更新一次。

2.单播

2.1单推接口

接口说明

接入方携带消息内容以及用户regId(或alias)进行通知消息推送。针对每个用户发送不同的通知。

使用场景:如物流、订单状态、游戏预约状态、行程状态、聊天(如微信、评论)等。

限制:根据客户端SDK订阅数自动配置,可发送的用户总量可以在开发者后台查看。

访问方式

URL编码方式协议methodContent-Type
/message/sendUtf-8httpsPOSTapplication/json
Curl e.g.:curl -X POST -H ‘authToken:${your_auth_token}’   -H     ‘Content-Type:application/json’  -d     ‘${your_request_body}’   https://api-push.vivo.com.cn/message/sendRequest body e.g.:{      “appId”:10004,      “regId”:”12345678901234567890123″,      “notifyType”:1,      “title”:”标题1″,      “content”:”内容1″,      “timeToLive”:86400,      “skipType”:2,          “skipContent”:”http://www.vivo.com”,        “networkType”:”1″,      “clientCustomMap”:{              “key1″:”vlaue1”,              “key2″:”vlaue2”    },    “extra”:{              “callback”:”http://www.vivo.com”,              “callback.param”:”vivo”    },          “requestId”:”25509283-3767-4b9e-83fe-b6e55ac6b123″}Response body e.g.:http status 200:业务成功:{         “result”:   0,         “desc”:   “请求成功”,”taskId”:   “121397329”}推送使用的regid或alias不合法,无法送达:{        “result”: 10302,        “desc”: “regId 不合法”,        “invalidUser”: {            “status”: 1,            “userid”:   “15638535410301000000001”      }}业务异常:{         “result”:   xxx,”desc”: “xxx不合法”} http status 500:Internet server error!

接口定义

输入参数:

intent uri

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
regIdstringN应用订阅PUSH服务器得到的id   长度23个字符(regId,alias 两者需一个不为空,当两个不为空时,取regId)
aliasstringN别名 长度不超过40字符(regId,alias两者需一个不为空,当两个不为空时,取regId)
notifyTypeintY通知类型 1:无,2:响铃,3:振动,4:响铃和振动
titlestringY通知标题(用于通知栏消息) 最大20个汉字(一个汉字等于两个英文字符,即最大不超过40个英文字符)
contentstringY通知内容(用于通知栏消息) 最大50个汉字(一个汉字等于两个英文字符,即最大不超过100个英文字符)
timeToLiveintN消息保留时长 单位:秒,取值至少60秒,最长7天。当值为空时,默认一天
skipTypeintY点击跳转类型 1:打开APP首页 2:打开链接 3:自定义 4:打开app内指定页面
skipContentstringN跳转内容 跳转类型为2时,跳转内容最大1000个字符,跳转类型为3或4时,跳转内容最大1024个字符,skipType传3需要在onNotificationMessageClicked回调函数中自己写处理逻辑。关于skipContent的内容可以参考【vivo推送常见问题汇总】
networkTypeintN网络方式 -1:不限,1:wifi下发送,不填默认为-1
classificationintN消息类型 0:运营类消息,1:系统类消息。不填默认为0
clientCustomMapJSON ObjectN客户端自定义键值对 自定义key和Value键值对个数不能超过10个,且长度不能超过1024字符, key和Value键值对总长度不能超过1024字符。app可以按照客户端SDK接入文档获取该键值对
extraJSON ObjectN高级特性(详见目录:一.公共——5.高级特性 extra)
requestIdstringY用户请求唯一标识 最大64字符
pushModeintN推送模式 0:正式推送;1:测试推送,不填默认为0(测试推送,只能给web界面录入的测试用户推送;审核中应用,只能用测试推送)
auditReviewJSON ArrayN第三方审核结果,参见:基于第三方审核结果的消息推送

 输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
taskIdstring任务编号
 invalidUserJSON Object非法用户信息,包括status和userid,userid为接入方传的regid或者alias,status有三种情况:1.userId不存在;2.卸载或者关闭了通知;3.七天不在线;4.非测试用户

3.广播

3.1保存群推消息公共体接口

接口说明

同一条信息覆盖多个用户。此接口需与批量推送用户接口3.2配套使用,批量推送接口用此接口生成taskId批量发送用户。

使用场景:活动、系统升级提醒等。

限制:默认根据客户端SDK订阅数自动配置。

访问方式

URL编码方式协议methodContent-Type
/message/saveListPayloadUtf-8httpsPOSTapplication/json
Curl e.g.:curl -X POST  -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’    -d   ‘${your_request_body}’   https://api-push.vivo.com.cn/message/saveListPayloadRequest body e.g.:{        “appId”:10004,        “title”:”标题1″,        “content”:”内容1″,        “notifyType”:1,        “timeToLive”:86400,        “skipType”:2,          “skipContent”:”http://www.vivo.com”,        “networkType”:”1″,        “clientCustomMap”:{              “key1″:”vlaue1”,              “key2″:”vlaue2”},          “requestId”:”25509283-3767-4b9e-83fe-b6e55ac6b123″}Response body e.g.:http status 200:业务成功:{         “result”:   0,         “desc”:   “请求成功”,”taskId”:   “342982232646905856”}业务异常:{         “result”:   xxx,”desc”: “xxx不合法”}http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
notifyTypeintY通知类型 1:无,2:响铃,3:振动,4:响铃和振动
titlestringY通知标题(用于通知栏消息) 最大20个汉字(一个汉字等于两个英文字符,一个表情占一个字符,即最大不超过40个英文字符)
contentstringY通知内容(用于通知栏消息) 最大50个汉字(一个汉字等于两个英文字符,一个表情占一个字符,即最大不超过100个英文字符)
timeToLiveintN消息保留时长 单位:秒,取值至少900秒,最长7天。当值为空时,默认一天。
skipTypeintY点击跳转类型 1:打开APP首页 2:打开链接 3:自定义 4:打开app内指定页面
skipContentstringN跳转内容 跳转类型为2时,跳转内容最大1000个字符,跳转类型为3或4时,跳转内容最大1024个字符,skipType传3需要在onNotificationMessageClicked回调函数中自己写处理逻辑。关于skipContent的内容可以参考【vivo推送常见问题汇总】 pushSDK版本号:480以上,不在支持skipType=3,自定义跳转统一使用skipType=4,详见【vivo推送常见问题汇总】中API接入问题的Q11中的intent uri示例。
networkTypeintN网络方式 -1:不限,1:wifi下发送,不填默认为-1
classificationintN消息类型 0:运营类消息,1:系统类消息。不填默认为0
clientCustomMapJSON ObjectN客户端自定义键值对 自定义key和Value键值对个数不能超过10个,且长度不能超过1024字符, key和Value键值对总长度不能超过1024字符。app可以按照客户端SDK接入文档获取该键值对。
requestIdstringY用户请求唯一标识 最大64字符
auditReviewJSON ArrayN第三方审核结果,参见:基于第三方审核结果的消息推送

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
taskIdstring任务编号

3.2批量推送用户接口

接口说明

批量发送用户。此接口与群推消息接口3.1配套使用,首先通过群推消息接口3.1返回taskId,然后此接口带上taskId批量发送用户,可以根据regIds或者aliases分批调用。每次调用时,regIds或者aliases的个数必须大于等于2,小于等于1000。

限制:根据客户端SDK订阅数自动配置,可发送的用户总量可以在开发者后台查看。

访问方式

URL编码方式协议methodContent-Type
/message/pushToListUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST -H   ‘authToken:${your_auth_token}’ -H       ‘Content-Type:application/json’  -d   ‘${your_request_body}’   https://api-push.vivo.com.cn/message/pushToListRequest body e.g.:{      “appId”:10004,      “regIds”:[              “12345678901234567890121”,              “12345678901234567890122”        ],          “taskId”:”342982232646905856″,          “requestId”:”25509283-3767-4b9e-83fe-b6e55ac6b123″}Response body e.g.:http status 200:业务成功:{    “requestId”: “25509283-3767-4b9e-83fe-b6e55ac6b123”,    “result”: 0,    “desc”: “请求成功”,    “invalidUsers”: [{        “status”: 1,        “userid”: “12345678901234567890121”    }]}
业务异常:{         “result”:   xxx,         “desc”:   “xxx不合法”}http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
regIdsstring[]NregId列表 个数大于等于2,小于等于1000(regIds,aliases   两者需一个不为空,两个不为空,取regIds)
aliasesstring[]N别名列表个数大于等于2,小于等于1000,长度不超过40字符(regIds,aliases 两者需一个不为空,两个不为空,取regIds)
taskIdstringY公共消息任务号,取saveListPayload返回的taskId
requestIdstringY请求唯一标识,最大64字符
pushModeintN推送模式 0:正式推送;1:测试推送,不填默认为0(测试推送,只能给web界面录入的测试用户推送;审核中应用,只能用测试推送)

输出参数:

  属性名字  类型  描述
  result  int  接口调用是否成功的状态码 0成功,非0失败
  desc  string  文字描述接口调用情况
  invalidUser  JSON Object  非法用户信息,包括status和userid,userid为接入方传的regid或者alias,status有三种情况:1.userId不存在;2.卸载或者关闭了通知;3.七天不在线;4.非测试用户

3.3全量发送接口

接口说明

向所有设备推送某条消息。

使用场景:活动、系统升级提醒等。

限制:默认是每个app每日可发送一条。

访问方式

URL编码方式协议methodContent-Type
/message/allUtf-8httpsPOSTapplication/json
Curl e.g.:curl -X POST -H     ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’     https://api-push.vivo.com.cn/message/allRequest body e.g.:{        “appId”:10004,        “notifyType”:1,        “title”:”标题1″,        “content”:”内容1″,        “timeToLive”:86400,        “skipType”:2,          “skipContent”:”http://www.vivo.com”,        “networkType”:”1″,      “clientCustomMap”:{              “key1″:”vlaue1”,              “key2″:”vlaue2”      },          “requestId”:”25509283-3767-4b9e-83fe-b6e55ac6b123″}Response body e.g.:http status 200:业务成功:{         “result”:   0,         “desc”:   “请求成功”,”taskId”:     “12139732”}业务异常:{         “result”:   xxx,”desc”: “xxx不合法”}http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
notifyTypeintY通知类型 1:无,2:响铃,3:振动,4:响铃和振动
titlestringY通知标题(用于通知栏消息) 最大20个汉字(一个汉字等于两个英文字符,一个表情占一个字符,即最大不超过40个英文字符)
contentstringY通知内容(用于通知栏消息) 最大50个汉字(一个汉字等于两个英文字符,一个表情占一个字符,即最大不超过100个英文字符)
timeToLiveintN消息保留时长 单位:秒,取值至少900秒,最长7天。当值为空时,默认一天
skipTypeintY点击跳转类型 1:打开APP首页 2:打开链接 3:自定义 4:打开app内指定页面
skipContentstringN跳转内容 跳转类型为2时,跳转内容最大1000个字符,跳转类型为3或4时,跳转内容最大1024个字符,skipType传3需要在onNotificationMessageClicked回调函数中自己写处理逻辑。关于skipContent的内容可以参考【vivo推送常见问题汇总】 pushSDK版本号:480以上,不在支持skipType=3,自定义跳转统一使用skipType=4,详见【vivo推送常见问题汇总】中API接入问题的Q11中的intent uri示例。
networkTypeintN网络方式 -1:不限,1:wifi下发送,不填默认为-1
classificationintN消息类型 0:运营类消息,1:系统类消息。不填默认为0
clientCustomMapJSON ObjectN客户端自定义键值对 自定义key和Value键值对个数不能超过10个,且长度不能超过1024字符, key和Value键值对总长度不能超过1024字符。app可以按照客户端SDK接入文档获取该键值对
requestIdstringY用户请求唯一标识 最大64字符
auditReviewJSON ArrayN第三方审核结果,参见:基于第三方审核结果的消息推送

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
taskIdstring任务编号

3.4获取消息推送的统计值接口

接口说明

获取taskId对应的统计信息,taskIds最多100个。 注意:查询的消息类型 【群推送消息/列表推消息】

访问方式

URL编码方式协议methodContent-Type
/report/getStatisticsUtf-8httpsGETapplication/json
Curl e.g.:   curl -X GET  -H   ‘authToken:${your_auth_token}’ -H       ‘Content-Type:application/json’     https://api-push.vivo.com.cn/report/getStatistics?appId=10004&taskIds=123138209,23498102,3240910940,109283018Request body e.g.:Response body e.g.:http status 200:业务成功:{        “result”:0,        “desc”:”请求成功”,      “statistics”:[    {          “taskId”:   “298475091219”,          “target”: 10000,          “valid”: 9500,          “send”: 9000,          “receive”: 9000,          “display”: 8000,          “click”: 200,          “targetInvalid”:   200,          “targetUnSub”:   200,          “targetInActive”: 100,          “covered”: 200,          “controlled”:   200,          “targetOffline”:   100    },    {          “taskId”:   “298475091220”,          “target”: 10000,          “valid”: 9500,          “send”: 9000,          “receive”: 9000,          “display”: 8000,          “click”: 200,          “targetInvalid”:   200,          “targetUnSub”:   200,            “targetInActive”: 100,          “covered”: 200,          “controlled”:   200,          “targetOffline”:   100    }]}业务异常:{         “result”:   xxx,         “desc”:   “xxx不合法”}http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
taskIdsstringY查询的任务列表taskIds 用,分隔开 e.g.:   “234567,234568”

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
taskIdstring任务号
targetlong目标总数
targetInvalidlong不存在的用户总数,根据id找不到任何信息
targetUnSublong解订阅的用户总数,用户已卸载或者客户端主动调用turnOffPush()解订阅
targetInActivelong14天不在网的用户数,手机14天没有联网,信息被后台删除
validlong有效目标总数
coveredlong被覆盖的用户消息总数,群推、全推、标签推消息属于营销消息,会被覆盖
controlledlong被管控的用户消息总数,例如接收的群推消息总数一天超过5条
targetOfflinelong推送后不在线的用户数,截止到当前统计时间为止,没有联网的用户数,呈下降趋势
sendlong下发总数
receivelong到达总数
displaylong展示总数
clicklong点击总数

4.回执

4.1消息送达回执

接口说明

vivo推送服务器将已送达或和对应设备的alias或者regId通过调用第三方设置的回调,http接口传给开发者服务器。仅单播支持回执(每次调用后,推送服务器会清空这些数据。)

使用:

① 发送消息接口设置扩展参数extra(详见目录:一.公共——5.高级特性 extra), 包含callback、callback.param。

② vivo推送服务器调用第三方设置的callback url接口。 

③ 字段ackType  【达回执类型】目前只有到达回执ackType=0

访问方式

URL编码方式协议methodContent-Type
第三方设置的callback url(详见:高级特性 extra)Utf-8https/httpPOSTapplication/json
Curl e.g.:   curl -X POST -H   ‘Content-Type:application/json’ -d     ‘${your_request_body}’   https://callbackurlRequest body e.g.:{      “taskId1”:{              “param”:”param1″,              “targets”:”alias1,alias2,alias3″,              “ackTime”:1612776166257    },      “taskId2”:{              “param”:”param2″,              “targets”:”regId1,regId2,regId3″,              “ackTime”:1612776166258    }}Response body e.g.:http status 200:http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
taskIdstringY任务编号
paramstringY开发者上传的自定义参数值
targetsstringY一批alias或者regId列表,之间是用逗号分割
ackTimelongN回执到达时间,毫秒时间戳

 回执流程

设备在线:

设备不在线:

5.标签管理

5.1 新增标签接口

接口说明

为应用方增加标签,用于后续标签推送。

访问方式

URL编码方式协议methodContent-Type
/tag/addUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d     ‘${your_request_body}’ https://host:port/tag/addRequest   body e.g.:{          “appId”:10004,          “name”:   “shenzhen”,          “desc”:”深圳用户标签”,       “group”:”city”}Response body   e.g.:http status   200:{         “result”: 0,         “desc”: “成功”,}业务异常:{         “result”: xxx,”desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
namestringY标签名称
descstringN标签描述
groupstringN标签分类名

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况

5.2 更新单个标签接口

接口说明

更新一个标签的信息,更新标签名字、描述、所属分类。

访问方式

URL编码方式协议methodContent-Type
/tag/updateUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tag/updateRequest   body e.g.:{           “appId”:10004,           “oldName”:”shenzhen”,           “newName”:”shenzhenbaoan”}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “成功”}业务异常:{         “result”: xxx,”desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
oldNamestringY旧标签名称
newNamestringY新标签名称
descstringN更新标签描述
groupstringN更新标签所属分类

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况

5.3 给标签添加用户设备接口

接口说明

给标签添加用户设备信息,单次不超过1000个设备。

访问方式

URL编码方式协议methodContent-Type
/tag/addMembersUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H ‘Content-Type:application/json’      -d ‘${your_request_body}’   https://host:port/tag/addMembersRequest   body e.g.:{         “appId”:10004,         “name”:”shenzhen”,         “type”:1,             “ids”:[“15549635570031000000216″,”15549635980031000001086”]}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “success”,    “data”: [          {                “status”: 1,                “userid”:   “00000000000000000000004”          },          {                “status”: 1,                “userid”:   “00000000000000000000005”          }    ]}业务异常:{         “result”: xxx,”desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
namestringY标签名字
typeintY用户类型:1是regId   ,2是别名
idsJSON ArrayY用户id

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
dataJSON Arrayuserid是非法用户id,status有3种状态:1是用户不存在,2是用户push开关关闭,3是用户14天未联网。

5.4 移除标签中的用户设备接口

接口说明

移除标签中的用户设备信息,单次不超过1000个设备。

访问方式

URL编码方式协议methodContent-Type
/tag/removeMembersUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tag/removeMembersRequest   body e.g.:{         “appId”:10004,         “name”:”shenzhen”,         “type”:1,         “ids”:[“15554239157791000000009″,”15554239157791000000008”]}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “success”,    “data”: [          {                “status”: 1,                “userid”:   “15554239157791000000008”          },          {                “status”: 1,                “userid”:   “15554239157791000000009”          }    ]}业务异常:{         “result”: xxx,         “desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
namestringY标签名字
typeintY用户类型:1是regId   ,2是别名
idsJSON ArrayY用户id

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
dataJSON Arrayuserid是非法用户id,status有3种状态:1是用户不存在,2是用户push开关关闭,3是用户14天未联网。

6.标签分类管理

6.1 新增标签分类接口

接口说明

为应用方增加标签分类,用于后续标签分类管理。

访问方式

URL编码方式协议methodContent-Type
/tagGroup/addUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d   ‘${your_request_body}’ https://host:port/tagGroup/addRequest body e.g.:{    “appId”:10004,    “name”:   “guangzhou”,     “type”:”city”}Response body   e.g.:http status   200:{         “result”: 0,         “desc”: “成功”,}业务异常:{         “result”: xxx,         “desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
namestringY标签分类名称
typeintY标签分类类型:1是普通标签,2是互斥标签
descstringN标签分类描述

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况

6.2 更新单个标签分类接口

接口说明

更新一个标签分类的信息,包括标签分类名称和描述。

访问方式

URL编码方式协议methodContent-Type
/tagGroup/updateUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tagGroup/updateRequest   body e.g.:{      “appId”:10004,      “oldName”: “city”,      “newName”:   “province”,      “desc”:   “这是更新后的描述”}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “成功”}业务异常:{         “result”: xxx,         “desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
oldNamestringY旧标签分类名称
newNamestringY新标签分类名称
descstringN新标签分类的描述

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况

6.3 添加标签到标签分类接口

接口说明

把标签添加进标签分类里面,一次可添加一个或者多个标签,最多不超过100个。

访问方式

URL编码方式协议methodContent-Type
/tagGroup/addToGroupUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tagGroup/addToGroupRequest   body e.g.:{         “appId”:10004,         “name”:”city”,         “tagList”:[“shenzhen”,”guangzhou”]}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “成功”}业务异常:{         “result”: xxx,”desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
namestringY标签分类名称
tagListJSON ArrayY一个或多个标签

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况

7.标签组合管理

7.1 新增标签组合接口

接口说明

为应用方增加标签组合。 一个标签组合由多个标签组成。

访问方式

URL编码方式协议methodContent-Type
/tagSegment/addUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d     ‘${your_request_body}’ https://host:port/tagSegment/addRequest   body e.g.:{    “appId”:10004,    “name”:   “segment1”,          “expression”:{                   “notTags”:[“shenzhen”],                  “andTags”:[],                  “orTags”:[]          }}Response body   e.g.:http status   200:{         “result”: 0,         “desc”: “成功”,}业务异常:{         “result”: xxx,”desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
namestringY标签组合名称
expressionJSON ObjectY标签组合表达式:包含三种JSON数组:notTags表示非操作、andTags表示与操作,orTags表示或操作,例如:”tagExpression”:{                 “notTags”:[“琴”,”棋”,”书”,”画”],                  “andTags”:[“深圳”,”广东”],                  “orTags”:[“本科生”,”研究生”]          }可以表示为,不会琴、棋、书、画的广东省深圳市的本科生或研究生的所有用户。当然这些标签需要先在平台或者接口创建后再使用。

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况

7.2 更新单个标签组合接口

接口说明

更新一个标签组合的信息

访问方式

URL编码方式协议methodContent-Type
/tagSegment/updateUtf-8httpsPOSTapplication/json
Curl e.g.:   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tagSegment/updateRequest   body e.g.:{            “appId”:10004,           “oldName”:”segment1″,           “newName”:”segment2″,”expression”:   {                    “orTags”: [“shenzhen”],                    “andTags”:     [],                    “notTags”: []    }}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “成功”}业务异常:{         “result”: xxx,”desc”:     “xxx”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
oldNamestringY旧标签组合名称
newNamestringY新标签组合名称
expressionJSON ObjectN新标签组合表达式:包含三种JSON数组:notTags表示非操作、andTags表示与操作,orTags表示或操作,例如:”tagExpression”:{                 “notTags”:[“琴”,”棋”,”书”,”画”],                  “andTags”:[“深圳”,”广东”],                  “orTags”:[“本科生”,”研究生”]          }可以表示为,不会琴、棋、书、画的广东省深圳市的本科生或研究生的所有用户。当然这些标签需要先在平台或者接口创建后再使用。

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况

8.标签推

8.1标签推接口

接口说明

接入方携带消息内容、标签信息进行通知消息推送。

  标签个数的限制:20个

访问方式

URL编码方式协议methodContent-Type
/message/tagPushUtf-8httpsPOSTapplication/json
Curl e.g.:curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/message/tagPushRequest   body e.g.:{          “appId”:10004,          “tagExpression”:{                   “notTags”:[“tag1″,”       tag2″,”tag3″,” tag4″],                  “andTags”:[“tag5″,”   tag6″],                  “orTags”:[“tag7″,”tag8”]          },  “segmentName”:   “组合名”,      “notifyType”: 4,    “title”:   “123”,      “content”: “456”,      “timeToLive”: 86400,      “skipType”: 1,      “skipContent”:   “assda”,      “networkType”: -1,      “requestId” :       “25509283-3767-4b9e-83fe-b6e55ac6b123”}Response body   e.g.:http status   200:业务成功:{    “result”:   0,    “desc”:   “请求成功”,    “taskId”:     “2199912448”}业务异常:{         “result”: xxx,”desc”:   “xxx不合法”}http status   500:Internet   server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
tagExpressionJSON ObjectY标签表达式。包含三种JSON数组:notTags表示非操作、andTags表示与操作,orTags表示或操作,例如:”tagExpression”:{                 “notTags”:[“琴”,”棋”,”书”,”画”],                  “andTags”:[“深圳”,”广东”],                  “orTags”:[“本科生”,”研究生”]          }可以表示为,不会琴、棋、书、画的广东省深圳市的本科生或研究生的所有用户。当然这些标签需要先在平台或者接口创建后再使用。
segmentNamestringN之前创建好的组合名,如果传递组合名,默认用组合名推送,否则如果传递tagExpression,按照标签表达式推送
notifyTypeintY通知类型 1:无,2:响铃,3:振动,4:响铃和振动
titlestringY通知标题(用于通知栏消息) 最大20个汉字(一个汉字等于两个英文字符,一个表情占一个字符,即最大不超过40个英文字符)
contentstringY通知内容(用于通知栏消息) 最大50个汉字(一个汉字等于两个英文字符,一个表情占一个字符,即最大不超过100个英文字符)
timeToLiveintN消息保留时长 单位:秒,取值至少60秒,最长7天。当值为空时,默认一天
skipTypeintY点击跳转类型 1:打开APP首页 2:打开链接 3:自定义 4:打开app内指定页面
skipContentstringN跳转内容 跳转类型为2时,跳转内容最大1000个字符,跳转类型为3或4时,跳转内容最大1024个字符,skipType传3需要在onNotificationMessageClicked回调函数中自己写处理逻辑。pushSDK版本号:480以上,不在支持skipType=3,自定义跳转统一使用skipType=4,详见【vivo推送常见问题汇总】中API接入问题的Q11中的intent uri示例。
networkTypeintN网络方式 -1:不限,1:wifi下发送,不填默认为-1
classificationintN消息类型 0:运营类消息,1:系统类消息。不填默认为0
clientCustomMapJSON ObjectN客户端自定义键值对 自定义key和Value键值对个数不能超过10个,且长度不能超过1024字符, key和Value键值对总长度不能超过1024字符。
requestIdstringY用户请求唯一标识 最大64字符
auditReviewJSON ArrayN第三方审核结果,参见:基于第三方审核结果的消息推送

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
taskIdstring任务编号

9.消息状态查询

9.1消息状态查询

接口说明

由于目前只返回审计相关信息,单推没有同步返回消息审计状态,其他类型的推送有同步返回。所以可通过调用此接口传递消息id,查询消息的状态。目前有调用频率限制,单个app 1次/s, 建议一批类似的消息体查询一次。

使用:

① 发送消息后查询消息的状态(延时在一分钟内)。

②‘审计通过’或 ‘审计不通过的状态还未入库’,返回 【消息状态未知】,审计不通过状态已入库,返回【消息包含敏感词】

访问方式

URL编码方式协议methodContent-Type
https://api-push.vivo.com.cn/search/msgStatusUtf-8https/httpGETapplication/json
Curl e.g.:   curl -X GET -H   ‘authToken:${your_auth_token}’ -H   ‘Content-Type:application/json’   -d     ‘${your_request_body}’ https://api-push.vivo.com.cn/search/msgStatus?appId=10004&taskIds=taskId1,taskId2Request body e.g.:{    “result”:   0,    “desc”:   “success”,    “data”: [          {                “taskId”: taskId1,                “desc”: “消息包含敏感词”          },          {                ” taskId “: taskId2,                “desc”: “消息状态未知”          }    ]}Response body e.g.:http status 200:http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
taskIdsstringY由多个taskId组成的字符串,多个taskId之间用逗号分隔,一次最多查询100个

10.查询失效id

10.1失效id查询

接口说明

由于用户卸载、客户端主动调用turnOffPush()解订阅、设备14天不联网还有一部分历史原因,可能造成推送的id无效。开发者可以根据推送时返回的InvalidUser对失效id做标记或者清除处理,或者单独查询本接口,将无效的id过滤,避免占用推送额度。

使用:

① 传递要查询的id,以及id的类型,后台根据保存的id,返回无效的id。

② 建议在推送低峰期,例如晚上或者凌晨调用,将保存的id一批批查询,避免影响应用的推送性能。勿高频调用。

访问方式

URL编码方式协议methodContent-Type
/invalidUser/checkUtf-8https/httpPOSTapplication/json
Curl e.g.:   curl -X GET -H   ‘authToken:${your_auth_token}’ -H   ‘Content-Type:application/json’   -d     ‘${your_request_body}’ https://api-push.vivo.com.cn/invalidUser/check    Request body e.g.:{      “appId”:10004,      “userType”: 1,      “userIds”: [            “15547801220021000000000”,            “15547801220021000000001”    ]}Response body e.g.:http status 200:{      “invalidUsers”: [            “15547801220021000000000”,            “15547801220021000000001”    ]}http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
userIdsstring[]Y用户id数组 ,单次最大100个
userTypeintYuserId的类型1:regId,2:alias

11.消息回收

11.1 消息回收接口

接口说明

此接口用于回收已发送给用户的消息。通过传递推送的消息id和具体的用户id、用户类型进行消息回收,消息回收接口调用量和调用速度会占用推送量级和推送速度。

限制:由我司运营人员配置。

消息撤回功能是平台提供给开发者紧急处理运营事故的工具,切勿日常频繁使用,以免对用户体验不当影响。

对于推送内容、应用行为等存在违规的,平台将按《vivo推送运营规则》进行相应处罚。

访问方式

URL编码方式协议methodContent-Type
/message/recycleUtf-8httpsPOSTapplication/json
Curl e.g.:curl -X POST -H ‘   authToken:${your_auth_token}’ -H ‘Content-Type:application/json’  -d ‘${your_request_body}’   https://host:port/message/recycleRequest body e.g.:{         “appId”:10004,         “taskId”:656079923690082304,         “userIds”:[“15762048080021000000007″,”15762048080021000000008″,”15762048080021000000009”],         “userType”:1}Response body e.g.:http status 200:业务成功:{         “result”:   0,         “desc”:   “请求成功”,”invalidUsers”: [         {            “status”: 1,            “userid”:   “15762048080021000000008”         },         {            “status”: 1,            “userid”:   “15762048080021000000008”         }      ]}业务异常:{         “result”:   xxx,”desc”: “xxx不合法”} http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送
taskIdstringY单播或广播返回的taskId
userIdsstring[]YuserId列表。个数大于等于1小于等于100
userTypeintY用户类型。1:regId;2:alias

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
invalidUsersJSON Array非法用户信息,包括status和userid,userid为接入方传的regid或者alias,status有三种情况:1.userId不存在 2.卸载或者关闭了通知 3.七天不在线

12.应用配置信息查询 

12.1 应用配置信息查询接口

接口说明

此接口用于查询应用配置信息,系统消息总量、运营消息总量、群推消息体总量、配置速度等信息、SDK订阅数。此接口限制了调用频率,请勿频繁调用。

访问方式

URL编码方式协议methodContent-Type
/report/getAppConfigUtf-8httpsGETapplication/json
Curl e.g.:curl -X GET -H ‘authToken:${your_auth_token}’   -H ‘Content-Type:application/json’  -d ‘${your_request_body}’     https://host:port/report/getAppConfig?appId=10004Response body e.g.:http status 200:业务成功:{      “result”: 0,      “desc”: “请求成功”,      “data”: {          “sysMsgCount”: 10000,          “marketMsgCount”: 100000,          “sdkSubCount”: 124,          “speed”: 3000,          “groupMsgBodyCount”: 12000,       “remainSysMsgCount”:1200,       “remainMarketMsgCount”:1300
      }}业务异常:{           “result”:   xxx,”desc”:   “xxx不合法”} http status 500:Internet server error!

接口定义

输入参数:

属性名字类型是否必填Y/N描述
appIdintY用户申请推送业务时生成的appId,用于与获取authToken时传递的appId校验,一致才可以推送

输出参数:

属性名字类型描述
resultint接口调用是否成功的状态码 0成功,非0失败
descstring文字描述接口调用情况
datajson object详细内容

data:

属性名字类型描述
sysMsgCountlong系统消息配置量
marketMsgCountlong运营消息配置量
sdkSubCountlongsdk订阅数
speedlong速度配置
groupMsgBodyCountlong群推消息体配置量
remainSysMsgCountlong剩余可发送系统消息量级
remainMarketMsgCountlong剩余可发送运营消息量级


全局公共返回码详解

resultdesc
0请求成功
10000权限认证失败
10040资源已达上限,稍后重试
10044该接口未开放测试模式
10045应用审核中不可发送正式消息
10050alias和regId 不能都为空
10051暂不支持该消息类型
10054notifyType 不合法
10055title 不能为空
10056title 长度不能超过40个字符
10057content 不能为空
10058content 长度不能超过100个字符
10059timeToLive 不合法
10060skipType 不合法
10061skipType = 2, skipContent 不能为空
10062skipType = 2, skipContent 不能超过1000个字符
10063skipType = 3, skipContent 不能为空
10064skipType = 3, skipContent 不能超过1024个字符
10065networkType 不合法
10066自定义key和Value键值对个数不能超过10个
10067自定义key和value键值对不合法
10068skipType = 4, skipContent 不能为空
10069skipType = 4, skipContent 不能超过1024个字符
10070运营消息发送量总量超出限制
10071超出发送时间允许范围
10072推送速度过快,请稍后再试
10073系统消息发送量总量超出限制。系统消息量级申请,请参见:系统消息量级说明
10082系统消息未开通
10084查询速度过快,请稍后再试
10085title 或 content 不能为纯表情
10093获取鉴权码速度过快
10094鉴权码与请求体对应的appId不一致
10101消息内容审核不通过
10102服务器端未知异常
10103推送内容含敏感信息
10104请发送正式信息,请检查title、content,不要发送测试内容
10105推必安内容审核不通过
10106auditReview参数错误
10110请配置商业化消息发送频率
10111今天已发送商业化消息
10112商业化消息发送超出周次数限制
10150aliases 和 regIds 不能都为空
10151taskId 不能为空
10152taskId 不合法
10153regIds 个数不在指定范围[2-1000]
10154aliases 个数不在指定范围[2-1000]
10155消息不存在或已过期
10200appId 不能为空
10201appKey 不能为空
10202appKey 不合法
10203timestamp 不能为空
10204sign 不能为空
10205appId 不存在
10206sign 不正确
10207timestamp 不合法
10250认证接口超过调用次数限制
10252批量发送创建消息体超出限制
10253批量发送regId或alais超过总量限制
10254全量发送超过次数限制
10301alias 长度不能超过40个字符
10302regId 不合法, regId为无效的regId, regId可能已经失效
10304extra 包含不支持的key
10305extra callback长度不能超过128个字符
10306extra callback.param长度不能超过64个字符
10307alias 不合法
10352requestId 不能为空
10353requestId 长度不能超过64个字符
10354Internet server error
10471taskIds 数量不能超过100个
10472taskIds 格式错误
10473taskIds 为空
10600name参数不合法,只能使用中文、英文字母、阿拉伯数字和下划线命名,且不能以数字开头,且长度不超过50字符
10601标签名字不能为空
10602标签描述不能超过300字符
10603oldName参数不能为空
10604newName参数不能为空
10605oldName参数不合法,只能使用中文、英文字母、阿拉伯数字和下划线命名, 且不能以数字开头,且长度不超过50字符
10606newName参数不合法,只能使用中文、英文字母、阿拉伯数字和下划线命名, 且不能以数字开头,且长度不超过50字符
10607id参数不能为空
10608type参数不能为空
10609ids参数不能为空
10610标签名已经存在
10611标签分类名已经存在
10612标签组合名已经存在
10613group参数不合法,只能使用中文、英文字母、阿拉伯数字和下划线命名, 且不能以数字开头,且长度不超过50字符
10614ids数量不能超过1000
10615tag数量不能超过100
10616type参数不合法
10700userids不能为空
10701userid个数超过限制
10702optionType错误
10703register接口调用超频,稍后再试
10704register调用过快,稍后再试
10705app不支持
10706userType错误
10800registration_tokens个数不在指定范围
10801notification不能为空
10802original_source_name不能为空
10803original_source_name长度非法
10804original_source_ip不能为空
10806click_action非法
10807url长度超过限制
10808intent长度超过限制
10255全量推送接口未开放
10901dyeKey长度不能超过限制
10900dye设置个数超过限制
10811超出限制
10810clientId非法
10809click_action不能为空
10805notification_channel长度超过限制
10617系统msgId生成异常
10500订阅标签超出限制
10501标签长度超出限制
10502标签已经删除完成
10503标签不能为空
10504订阅标签超出限制
10505标签长度超出限制
10506标签已经删除完成
10507标签不能为空
10508标签个数超出限制
10550标签操作类型无效
10551标签列表不能为空
10552标签个数超过限制
10553标签组合名不能为空
10309audienceId不合法,alias长度不超过40

vivo推送消息分类说明

为优化用户在手机中的推送消息体验,解决 “用户无法分辨并自主控制真正想要收到的消息”这类问题,我们将消息分为:系统消息、运营消息两个类别进行管理。开发者需根据自身应用的通知场景,将消息内容按照对应消息类别发送。

一、分类说明

根据用户对推送内容的关注程度,划分为“系统消息”、“运营消息”两个消息类别,不同类别对应不同的权限,消息类别及对应权限的映射关系如下:

消息类别划分原则允许发送的内容增量申请方式管控规则(总量管控+频控管控)接入方式
系统消息用户对收到此类消息有预期,并需要及时知道的消息,如果错过可能会导致不良影响。• 即时消息• 邮件• 用户设置的提醒• 物流• 订单• 待办待阅读• 财务• 功能提醒详细内容参考文中消息分类场景说明邮件申请,申请模板及要求见下文此接口已对外公开总量管控:默认等于3倍的用户订阅数,免费申请增量频控管控:单用户单应用每天收到的消息条数无上限开发者接口设置参数(classification=1),开发文档详见《服务端API接口文档》
运营消息用户对收到此类消息无预期,关注程度较低。除“系统消息”允许发送内容以外的内容推荐、活动推荐、社交动态等通知。详细内容参考文中消息分类场景说明商务申请此接口已对外公开总量管控:默认等于1倍的用户订阅数,商务申请增量频控管控:单用户单应用每天收到的消息条数上限5条开发者接口设置参数(classification=0),开发文档详见《服务端API接口文档》

注意: Funtouch OS_10及以上版本已取消消息盒子,取消盒子正在向OS10之前版本覆盖。

二、消息分类场景说明

1.【系统消息】场景概述

系统消息接口仅允许即时消息、邮件、用户设置的提醒、物流、订单、待办待阅读、财务、功能提醒8类消息推送:

序号系统消息类型场景概述具体场景
1即时消息聊天消息(私信、私聊、群聊)包括聊天消息中的图片、文件传输、语音/视频通话,不包括官方号或者商家批量推送给用户的私信、广告
2邮件邮件的发送、接收状态信息如:邮件发送成功提醒、收到新邮件通知等
3用户设置的提醒用户在APP内主动设置的提醒信息或弹窗确认会收到推送的提醒信息如:设置的签到打卡提醒;主动设置的开播提醒、书籍更新、付费的订阅内容更新等;设置的商品或机票降价、商品开团提醒等
4物流物流节点信息包括收发货,派送,签收,取件通知等
5订单订单生成信息及订单状态变化如:下单成功、卖家收到新订单、订单详情、订单状态、物流状态、订单售后、订单投诉处理进度、开票信息等
6待办待阅读个人事项提醒(用户待处理业务流程或者待阅读的通知)如:审核进度提醒、认证状态等流程提醒;商品库存不足、商品售罄、商品下架等通知;工单处理、限制提现、客诉警告、店铺限制、商品黑名单、交易违规、涉假/涉欺诈发货等通知;常旅信息到期、证件过期等提醒;路况提醒、行程通知、出行服务生成的检票、到达、延误、晚点等行程通知等
个人状态变化包括账号上下线、账号信息认证、等级权限变更等
个人设备提醒包括智能设备、监控设备的系统提醒、设备报警等
7财务个人交易提醒包括收付款、银行到账&扣款、催缴&退款信息、充值,涉及金额、账单、交易提醒、贷款受理进度、还款/逾期提醒、资金冻结提醒、资金限制提醒、缴纳保证金提醒、红包到账(非促销类红包)等
个人资源变化(用户有偿的虚拟资源及非促销类增值服务变化提醒)包括用户个人的虚拟财产如积分/余额等变更提醒,以及增值服务的充值/到期/续费/到账提醒等(虚拟财产必须是非促销类的, 促进用户增长的领金币或促销类红包/优惠券不属于“系统消息”)
8功能提醒用户操作了系统功能后的结果通知如:“共享单车已关锁还车,点击查看详情”

2.【运营消息】场景描述

不允许通过系统消息接口发送运营消息,包括但不限于广告、推广、活动等对用户有主动运营作用的推送,或者其他非用户主动触发的信息;未订阅的影音视听内容、商品推广、宣传,或者折扣、红包、领劵优惠信息等。

序号运营消息类型场景描述
1内容推荐非用户主动订阅,APP向用户推送的资讯、内容。如:微博、资讯、新闻、点评、小说、广告、视频、音频、直播等等
2陌生人推荐大V、主播、异性、可能认识的人等
3金融理财金融理财产品推荐。   如:投资、贷款、股票、基金、贵金属等
4促销活动及推荐商品推广、宣传、折扣、红包、领劵、返现等优惠信息;推荐产品功能、服务更新,商品、商家、店铺推荐的内容,例如“您的授信额度增加”
5业务到期提醒提醒用户保险、医疗、水电到期续保续费,或者话费、会员等月结日充值提醒等服务续期类推送
6运营活动各类APP内非用户主动设置的需用户参与的活动提醒消息、小游戏提醒、服务或商品评价提醒等。   如:抽奖、积分、签到、任务、分享、偷菜、领金币等
7天气天气预警提醒
8社交动态用户之间的社交互动提醒,如:添加好友、被赞、被@、评论、留言、关注、转发、回复
9订阅信息关注的人发布作品,如:关注的人直播提醒、动态更新

3.特殊场景消息归档

以下特殊场景可按消息归档模板提供相应材料发至邮箱push@vivo.com申请归为系统消息中的“用户设置的提醒”:

①【社交动态】满足以下交互要求可申请归为系统消息:弹窗和用户确认将收到该类别的PUSH通知,用户可选择“接收”或“取消”,选择接收后可加入“系统消息”分类。如顾客对门店的点评提醒、老师对作业的点评提醒可申请归为系统消息。

②【订阅信息】满足以下交互要求可申请归为系统消息: 用户点击订阅后,弹窗和用户确认将收到该类别的PUSH通知,用户可选择“接收”或“取消”,选择接收后可加入“系统消息”分类。如关注的主播开播提醒、特别关注的账号/作者发布动态属于【用户设置的提醒】类“系统消息”,而普通关注了账号/作者且未确认动态更新会推送的动态更新属于【订阅信息】,只能从运营消息接口发送。

特殊场景消息归档模板(仅限运营消息中社交动态、订阅信息)

邮件标题: Vpush系统消息归档申请   – 应用名称
邮件正文:您好,因我司应用XX(应用名称)部分消息属于用户主动订阅,参考《推送消息分类说明》,判断以下场景符合“用户设置的提醒”,申请归档为系统消息,请vivo推送团队核实。应用名称:XXAppId:XXXX应用包名:XXXX
消息模板说明消息模板/样例(标题+内容)证明材料(弹窗截图/录屏)
例:房源动态变更通知标题:你关注的【****】,有新上房源内容:点击查看
注意:消息模板说明是指消息的内容类别,如:设置的签到打卡、开播提醒、书籍更新、付费订阅内容更新、商品或机票降价、商品开团提醒等。需要列举所有希望归档为系统消息发送的消息模板。

三、开发者接入流程

1.通过API传入相应参数

①系统消息只能通过API接口创建,web端运营平台暂不支持此功能。API接口新增请求字段classification,“0”代表运营消息,“1”代表系统消息,不填默认为0。

②相关错误码(开发文档详见《服务端API接口文档》

10073:系统消息发送量总量超出限制

10082:系统消息开关未打开

2.智能分类二次修正

①参数传“0”代表运营消息,不经过智能分类二次修正,直接从运营消息总量扣除额度,并受用户接收条数限制的频控;

②参数传“1”代表系统消息,经过智能分类二次修正,若智能分类识别出不是系统消息,会自动修正为运营消息,并扣除运营消息额度;若识别为系统消息,则从系统消息总量扣除额度。

③部分特殊情况下,会出现误判,智能分类可能会将系统消息判定为运营消息。发生此情况时,请按下面误判反馈邮件模板填写发送至:push@vivo.com

主题:XX应用消息分类误判反馈内容:……应用名称(含包名):……误判类型:系统消息误判为运营消息误判消息:逐条展示(超过5条必须附上表格明细)附件:误判消息明细

④开发者通过邮件反馈智能分类误判情况,平台再通过线上纠错,减少反馈的消息类型误判情况。

四、消息分类接入规范

1.严格限制系统消息发送量级和发送消息类型

①限制发送量级:默认3倍SDK订阅数的系统消息量级。

②若无法满足系统消息的实际需求量级,可以单独额外申请。需要保证申请量级完全符合实际推送量级,禁止申请后又不使用的情况发生,平台会根据实际情况下调系统消息量级。(系统消息量级申请请使用下方邮件模板)

③限制发送的系统消息类型:目前仅限于前文中即时消息、邮件、用户设置的提醒、物流、订单、待办待阅读、财务、功能提醒8类消息允许推送。

2.不允许通过系统消息接口发送运营消息

包括但不限于广告,推荐,推广,活动等对用户有主动运营作用的推送,或者其他非用户主动触发的信息;未订阅的影音视听内容、商品推广、宣传,或者折扣、红包、领劵优惠信息等。

五、运营监管及处罚

vivo推送平台日常巡查消息分类的接入情况,如发现推送内容不符合要求的,将进行违规处罚,特别是将运营消息通过系统消息渠道滥发的将会严格处罚。

1.违规界定

对于开发者违规滥用系统类消息,包括:使用系统消息通道发送运营消息、用户投诉消息产生打扰。

常见运营消息类型如:

①消费优惠类通知、商品降价类通知、商品更新提醒类通知等一些涉及消费的营销类通知。

②涉及红包、卡券、优惠券、积分类消息偏社交属性的推送

③关注的主播发表作品、评论、点赞、回复等消息

2.运营监管

平台将按消息分类标准,对API接口字段classification为“1”的消息(即系统消息)进行每日巡检,巡查开发者以系统消息渠道发送运营消息的情况,并按违规程度及频次进行相应处罚,最高将关闭消息推送功能。

3.处罚标准

根据违规程度,执行以下处罚标准:

处罚与整改同步进行,违规处罚应用需按要求限期整改,接受处罚并提供整改排期,整改完成后邮件通知vivo推送平台并全量发布。

逾期未整改完成需提前邮件申请延长整改时间并说明缘由,逾期无故未整改,视为再次违规,进入下一档处罚

违规整改期结束后,后续点检如再次出现违规行为,将视为新一轮违规并执行相应处罚。

Vpush通知系统消息渠道滥用处罚规则
若违规量级过大,vivo推送平台将视影响范围/严重程度/违规频次,酌情加重处罚措施
违规频次处罚内容整改期限
首次邮件警告30个自然日
第二次降低系统消息日推送量级20% 14个自然日
第三次降低系统消息日推送量级50% 7个自然日
第四次暂时关闭系统消息推送功能,直至整改完成
开通系统消息1倍SDK订阅量观测14个自然日
开通系统消息2倍SDK订阅量观测14个自然日
恢复至默认配置(即3倍SDK订阅量)

①    降低系统消息日推送量级在应用现有量级上计算;开通系统消息量级在3倍SDK订阅量级上计算。

②    第四次违规整改完成后,开发者需提交恢复申请,平台将梯度开通系统消息日推送量级,梯度时间结束后开发者需再次发送恢复申请,进入下一个梯度观测。

③    若梯度观测时违规,将再次暂时关闭系统消息推送功能。若梯度观测无违规,将在30个自然日后恢复系统消息量级,此后再次违规将重新计次。

注意:处罚期间,开发者不得以系统消息量级不足申请额外增量

4、整改排期

如应用因违规而被限制系统消息推送权限,接收处罚通知后需向push@vivo.com发送“系统消息渠道违规整改排期”,并附上整改内容。

整改排期模板

邮件标题:Vpush系统消息渠道违规整改排期 – 应用名称
邮件正文:您好,我司应用XX(应用名称)于XXXX年XX月XX日,被vivo推送团队告知由于XX触发系统消息渠道滥用违规。当前,我司根据相关规范进行整改,整改完成后将邮件同步整改结果。同时,我司承诺:不再出现利用系统消息渠道发送运营消息的行为。应用名称:XXAppId:XXXX应用包名:XXXX整改排期:XXX整改完成时间:XXX (须在对应整改期限内)
整改内容:经排查,以下消息不符合系统消息分类规则,现改为通过运营消息渠道发送。
消息类别消息模板/样例(标题+描述)
注意:消息类别是指消息的内容类别,如:新闻资讯、营销活动、社交动态提醒等。需要列举所有整改的消息类别,每一种类别至少列举一种消息模板或样例(包括消息标题和描述)。

5、误判申诉申请

如应用因误判违规而被限制系统消息推送权限,可向push@vivo.com发送“系统消息误判申诉”,并附上误判类型及示例。

消息误判申诉模板:

邮件标题: Vpush系统消息误判申诉 – 应用名称
邮件正文:您好,我司应用XX(应用名称)于XXXX年XX月XX日,被vivo推送团队告知由于XX而被降低/关停系统消息推送能力。参考《推送消息分类说明》,认为以下消息为系统消息误判为运营消息,请vivo推送团队核实。应用名称:XXAppId:XXXX应用包名:XXXX
申请内容:以下消息我司认为符合系统消息分类规则,申请继续使用系统消息渠道发送。
消息类别消息模板/样例(标题+描述)
注意:消息类别是指消息的内容类别,如:新闻资讯、营销活动、社交动态提醒等。需要列举所有希望继续使用系统消息渠道发送的消息类别,每一种类别至少列举一种消息模板或样例(包括消息标题和描述)。

6、恢复权益申请

如应用因违规而被限制系统消息推送权限,可在整改完成后向push@vivo.com发送“系统消息推送权益恢复申请”,并附上整改报告。

整改完成恢复权益模板:

邮件标题: Vpush系统消息推送权益恢复申请 – 应用名称
邮件正文:您好,我司应用XX(应用名称)于XXXX年XX月XX日,被vivo推送团队告知由于XX而被降低/关停系统消息推送能力。当前,我司已根据相关规范对违规消息进行整改,整改报告见附件。同时,我司承诺:不再出现使用系统消息渠道发送运营消息的行为。请vivo推送团队:恢复XX(应用名称)的系统消息推送权益。应用名称:XXAppId:XXXX应用包名:XXXX
申请内容:经排查,以下消息不符合系统消息分类规则,现已改为通过运营消息渠道发送。
消息类别消息模板/样例(标题+描述)
注意:消息类别是指消息的内容类别,如:新闻资讯、营销活动、社交动态提醒等。需要列举所有整改的消息类别,每一种类别至少列举一种消息模板或样例(包括消息标题和描述)。

vivo推送团队收到申请后,将对应用提交的整改报告进行审核巡检,如审核通过将恢复该应用的系统消息推送权限。

申请通过恢复权限后,平台再次监控到违规消息,将视为新的违规。

六、常见问题

Q1:什么时候开始进行运营消息频控?

为保证用户不被过多的运营消息打扰,平台将从2020年6月1日起,对运营消息进行每日频控限制,即单用户接收单个应用每天推送的运营消息条数上限为5条;

Q2:一直不接入消息分类会有什么负面影响?

若未接入消息分类,将导致所有消息默认按照运营消息类别下发,受到用户接收条数频控限制;

Q3:如果将社交动态、订阅信息等运营消息误传为系统消息怎么办?

线上智能分类会进行2次修正,线下将会按照处罚标准进行处罚;

Q4:系统消息量级不够用怎么办?

若系统消息量级不够用,可以邮件特殊申请实际需求的系统消息量级,按照下面的邮件模板填写信息后发送至邮箱:push@vivo.com

主题:xxx应用申请增加im消息/系统消息发送量级正文:……应用名称:……应用ID:……包名:……应用简介:……系统消息需求量级:……(申请后总量)数据佐证:……具体推送场景说明:如即时消息(应用内用户聊天消息)、订单(订单状态变化消息)

vivo推送使用指南

本文档主要介绍使用vivo推送的方法,以帮助开发者更快速便捷的使用vivo推送。

一、测试推送

1.推送方式

在开放平台创建应用及申请推送服务后,无论应用是否上架,开发者都可以通过API发送测试推送进行调试。

2. 展示内容及各操作详情

① 进入发送推送环节,展示下图应用层面界面,点击首行文字旁图标可进行各栏目条件筛选。

▶应用类别:现支持“移动应用”和“快应用”

▶推送权限:现支持正式权限、受限权限和无权限

正式权限:可在Web界面和API后台发送正式消息,也可在API后台向设置的测试设备发送测试消息进行测试

受限权限:不可在Web界面和API后台发送正式消息,可在API后台向设置的测试设备发送测试消息进行测试

无权限:因违反运营规则被处罚不可发送任何类型的消息

▶审核状态:

审核状态为未通过、审核中,推送权限为受限的应用不能通过vivo推送平台发送正式推送消息,可在API向测试设备发送测试消息

审核状态为已通过、推送权限为正式的应用可通过vivo推送平台发送正式推送消息,也可在API向测试设备发送测试消息

② 推送权限为受限时 ,审核状态为审核中或未通过,“操作”栏目下包含三种操作

▶应用信息:点击后进入应用的详细信息页面

▶测试设备:点击后进入测试设备管理页面

▶删除:删除该应用(无法恢复),快应用不可删除

3. 测试设备

新增测试设备管理页面,在申请推送服务后即可对测试设备进行管理,推送权限为“受限”的应用只能通过API向在Web页面中添加的测试设备发送测试消息。

测试推送仅支持对后台录入的测试设备发送消息,测试设备数量上限为20个,测试消息不受量级和频控限制。

发送测试消息时注意填写pushMode=1。(pushMode字段:0:正式推送;1:测试推送,不填默认为0)

备注:

1.测试推送,只能给web界面录入的测试用户推送;审核中应用,只能用测试推送

2.若未设置pushMode=1进行测试,文案相同时,将被当做重复推送的运营消息被去重

二、新建推送

1.推送方式

在应用及推送服务申请审核通过后,开发者可以通过两种方式:

① 调用API接口单发

② 审核通过后,即可在应用详情列表进行消息推送和管理

2. 展示内容及各操作详情

① 进入发送推送环节,展示下图应用层面界面,点击首行文字旁图标可进行各栏目条件筛选

▶应用类别:现支持“移动应用”和“快应用”

▶推送权限:现只支持正式推送,测试应用推送已关闭

▶审核状态:申请未通过、审核中的应用不能通过vivo推送平台发送推送消息

② “操作”栏目下包含四种操作

▶新建推送:指的是新建该应用的一条消息

▶应用信息:点击后显示该应用的详细信息,如下图所示

正式权限的应用支持“重置secret和恢复上一次secret”按自然日计算每天只可重置一次

▶删除:删除该应用(无法恢复),快应用不可删除

3. 推送消息创建

新建推送界面下,包含消息编辑以及人群目标,其余设置可点击“可选设置”进行设置,并且右侧会在模拟机上显示推送实际效果参考,功能详细说明和注意事项如下:

① 推送页面

② 可选设置

③ 在“推送工具-通知栏消息-新建推送”页面,您填写推送消息的标题、内容(标题和内容均可插入emoji表情)、用户群设置、推送时间、选择时间是否显示等推送内容和高级设置,并且右侧会在模拟机上显示推送实际效果参考。功能详细说明和注意事项如下:

④ 确认推送内容后,点击确认推送发送推送内容

4. AB test分组对比测试推送

在创建AB test栏目中,可将用户分为AB两组,在小范围内进行区别推送(例如相同用户推送不同内容、不同用户推送相同内容)测试,根据数据反馈结果,选择最优推送方案。在填写测试名称、选择测试模式、测试人群、完善内容设置、选择发送形式和填写高级设置后,可点击测试预览向测试设备发送所有的测试组观察效果。

① 测试名称:不会展示给用户,只在消息记录中显示便于分辨各个测试。

② 测试模式:分为对比通知文案和对比用户群体两种。

③ 测试人群:按条件筛选,在进行测试组人群筛选时可选择输入参与用户人数或滑动选择用户比例两种方式之一;按条件筛选支持文件上传功能,最大10M,无需压缩 ,TXT格式。

④ 发送形式:分为自动发送和手动发送两种。

⑤ “文案选择指标”和“判定文案时间”:在自动发送时,选择判定最优文案(人群)的指标和判别时间。文案选择指标为“到达率”“展示率”“点击率”(默认点击率)。三者单选,判定文案时间设置下拉栏,内容为1h/5/10/15/20h。

三、消息记录

创建消息提交后,将进入“消息记录”列表。

1. 通知栏消息消息记录

① 消息记录列表中可通过关键字、ID 、推送时间、创建方式(包含开放平台和API调用)和推送状态来搜索定位推送消息。其中审核中是因超过一定量级的消息需要进行人工审核,目前审核量级为10w以上,同时消息已停止是因终止发送,详情请见“终止发送”功能详解。

② 消息记录信息栏目下,包含“浏览栏”与“操作栏”。

浏览栏包含:消息ID、标题、内容、推送时间、推送状态及发送量、到达量、展示量和点击量的数据展示;

操作栏包含:详情、实时统计、终止发送、消息撤回。

▶详情:点击详情展示创建推送消息时填写的内容。

▶实时统计:点击“实时统计”进入消息统计页面, 可以看到该消息的基本信息和查看不同维度的统计趋势,包含推送基本信息、推送内容、推送下发进度、设置、整体数据、推送转化分析、推送时效分析、数据详情。

▶终止发送: 当任务处于「发送中」时,您可以点击「终止发送」来终止推送。但已经收到推送的用户无法进行终止,点击终止发送弹出提示框进行提示。

▶消息撤回:平台与API均支持消息撤回功能。且Web端消息记录不展示API创建的群推消息,则此类消息在web端将无法进行撤回。

① 通知栏消息与AB test消息均具备此功能,此功能是指消息下发到达到客户端并展示未点击可将消息进行回收,用于消息发生重大事故时使用,对已下发并到达客户端的消息进行撤回,消息撤回后将变为 “已撤回”状态;

② 单个应用每天(0:00-24:00)仅可操作一次,且在48小时内支持消息回收(API无时间限制);

③ 消息撤回不会返还已消耗的额度,请谨慎操作!

在使用此功能时请注意,消息撤回功能是平台提供给开发者紧急处理运营事故的工具,切勿日常频繁使用,以免对用户体验不当影响。对于推送内容、应用行为等存在违规的,平台将按《vivo推送运营规则》进行相应处罚。

2. AB test消息记录

① 新增AB test消息选择框体,展示AB test消息记录,消息记录列表中可通过关键字、推送时间检索。

② 消息记录分为两个框体:对比通知文案和对比用户群体,点击不同按钮会显示不同的消息记录。

2.1 对比通知文案和对比用户群体

对比通知文案消息记录,内包括测试名称、推送时间(AB test开始发送的时间)、推送状态、发送模式、测试人群、标题、内容、到达数|率、展示数|率、点击数|率、操作;对比用户群体同理。在对比通知文案和对比用户群体测试中,分条数显示各测试组数据,并将正式组数据加在对应测试组上,用底色标注正式组发送的是哪条测试组的内容

Ø根据测试组数量增加标题、内容、到达量/率、展示量/率、点击量/率的行数

2.2 操作栏

共计有四个选项:详情、实时统计、终止发送、手动发送,根据不同的推送状态出现不同的选项。

Ø手动发送:手动发送中,在AB test测试组后台判断发送完成后,才会出现,点击手动发送后显示可选文案如图:

Ø 详情页:点击详情按钮,弹出详情消息框。如图所示

Ø 实时统计:推送文案+基本信息+ 推送下发进度+整体数据+推送转化分析+推送折损漏斗+推送时效分析+数据详情

ü 推送文案:推送文案中包含标题、内容、跳转方式、跳转内容、测试人群、用户比例或用户数量

ü 基本信息:基本信息中包含应用名称、推送时间、测试模式、发送形式、文案选择指标+判定文案时间、键值对、联网方式、时间显示、提示音、消息有效期及推送下发进度。

ü 整体数据如图所示,分为各个测试组及正式组显示,更加详尽的展示各组数据,点击右上角不同组可显示不同组数据(包含正式组)。

ü 推送转化分析:柱状图形式,同时展示各测试组及正式组的推送转化情况,正式组叠加在所选测试组的数据上。

ü 推送折损漏斗:推送折损漏斗显示因什么原因折损的消息,叠加柱状图显示

ü 推送时效分析:推送时效分析同上上方展示各测试组可选,并且右上角可选发送量,到达量、展示量、点击量。最右上角显示1小时和24小时,如图:可分别点选某个数据来看各个测试组和正式组的数据对比

ü 数据详情:可分别观察各个测试组和正式组的实时数据详情。

Ø 终止发送:点击终止发送按钮,实时统计数据截止到终止发送为止

四、推送数据

在“推送统计-推送数据”可查看该应用下数据统计总览以及详细数据列表。上表中可查询“全部统计”和“单推统计”

1. 全部统计

实时数据(包含当日消息总量、用户订阅数、运营消息总量、系统消息总量)、实时数据趋势图、数据趋势、折损统计分析、数据详情展示。

如有疑问可移至气泡弹窗或进入文档中心,内有各个名词的详细解释。《名词/指标解释》

2. 单推统计

① “全部统计”较“单推统计”在实时数据中增加当日消息总量、用户订阅数、运营消息总量和系统消息总量数据统计。

② 可将数据详情以表格形式导出

五、标签管理

1. “创建标签”及“添加用户”

第一步:“标签管理”创建好标签; 第二步:在对应的标签里 “添加用户”

注:API添加的用户在push开放平台不可见用户详情,只显示用户数

2. 标签分类

① 点击“创建分类”输入名称,描述,选择“是否互斥关系”标签组内设置为互斥时,组内标签之间为互斥关系,即一个用户最多只能有该组内一个标签。设置确定后,将不可以更改互斥关系,请谨慎操作。

② 创建好分类后,在对应的分类里“添加标签”

③ 当单个标签不满足业务场景推送时,可以在“标签组合里”对标签进行“并交差”组合

▶点击“创建组合”输入名称

▶勾选多标签组合,在对应的并交差集里添加标签并保存

六、在线诊断

推送后台提供一站式服务能力,从消息推送到消息数据分析的呈现来排查推送中出现的问题。

点击“在线诊断”功能模块,可进行自助查询设备与消息的送达、在线情况,包括

l  设备是否收到指定消息:可以根据“regid”、“alias”+消息id,查询消息是否送达

l  设备最近是否在线:可以根据“regid”、“alias”,查询设备是否在线。

查询结果覆盖以下场景:

诊断结果详细说明
消息被管控提示单设备单应用每日有5条运营消息频控,系统消息不受限制请参考推送消息分类说明:推送消息分类说明
被拉起activity未找到配置的跳转参数不正确,请检查skipcontent参数的配置参考客户端SDK集成指南第四点的打开自定义页面进行配置参数
用户不存在提示检查输入的regid是否正确
用户解订阅提示用户没有订阅push,检查调用turnOnPush是否成功
未查到结果提示只能查询最近两天的消息,超过两天查询不到消息日志更新可能有延迟,请稍后再查
内容审核拦截提示消息内容审核不通过
消息被覆盖提示离线的运营消息被新的运营消息覆盖
用户未联网提示用户没有连接网络
消息已送达并展示提示消息已经到达设备并且展示在通知栏
消息已送达未展示提示消息已经到达设备,但是没有展示在通知栏,一般提示里面都会带上未展示原因,可以根据原因进行排查
消息id格式错误提示查看输入的消息ID是否有误,消息ID是一串纯数字,对应服务器接口回调的taskid
设备在线不在线提示设备不在线,查一下设备的联网状态
90天不在线提示用户长时间没有联网

结果示例:

七、顶部导航栏

1. 消息中心

点击顶部导航栏“消息中心”进入消息中心页面,查看平台消息通知及重要公告。

2. 联系信息

点击顶部导航栏“下拉箭头-联系信息”进入联系信息管理页

3. 文档中心

点击顶部导航栏“文档中心”,进入文档中心页面,页面首页为“push推送—vivo推送产品说明”

4. 平台首页

点击顶部导航栏“推送运营平台”可回到推送运营平台首页

八、联系我们

客服咨询:开放平台首页-客服咨询

邮箱:push@vivo.com

参考文档:

《名词/指标解释》

《服务端API接口文档》

《客户端API接口文档》

《FAQ》

《vivo推送平台服务协议》

vivo推送接入流程

本文档主要介绍启用vivo推送的步骤,以帮助开发者更快速的完成vivo推送的接入。

一、注册vivo开发者账号

请访问vivo开放平台,使用vivo账号登录进入开发者站,如果没有vivo账号需要先注册vivo账号。 

详细开发者账号注册流程请参考《企业开发者注册》。

推送服务将同步开放平台上架应用结果,请关注开放平台应用的上架状态,开发者可在申请页面查看审核结果。 

二、登录vivo推送平台启用推送

若要使用vivo推送平台进行推送,开发者的应用必须要在开放平台通过审核上架后,才会通过消息推送服务审核。

1. 创建应用

创建正式推送:创建正式推送前需先在开放平台创建您的应用。详情请见《应用创建/更新流程》。

2. 申请push服务:

当开发者已经创建应用后,无论应用审核通过与否均可申请push服务。

在登录vivo开发者账号后,申请push服务有以下方式:

① 开放平台首页-产品-应用分发-运营-消息推送进入:https://dev.vivo.com.cn/promote/pushNews

② 开放平台首页-管理中心-常用服务-推送服务进入:https://dev.vivo.com.cn/manageCenter

点击进入消息推送后,将会进入“vivo开放平台-推送运营平台”,在“消息推送-全部应用”中点击“创建应用”;

若此操作在开发者创建应用后,所创建应用将会列入在应用名称里,点击“应用名称”选择要申请的应用后点击“提交申请”。

若先进入此步骤,略过了创建应用环节,可点击“开放平台-创建应用”跳转到相应界面,详细流程请见《应用创建/更新流程》

若已有应用点击提交申请后,推送服务将同步开放平台上架应用结果,请关注开放平台应用的上架状态,开发者可在申请页面查看审核结果。

三、“应用信息”中获取APPID/key/secret

四、集成push服务SDK并在Web页面添加测试设备

1、集成含push服务的客户端SDK,具体参考《客户端SDK集成指南》

2、在Web页面添加测试设备

五、API向指定测试设备发送测试消息联调

具体参考《接入push服务注意事项》– “七、如何发送测试消息图解”

六、在开平上传含有push服务的APK

完成vivo开放平台注册后登录,点击进入【管理中心】

1、点击“管理中心-应用分发-应用”

2、点击“创建应用

3、按流程指引创建应用/游戏,完善信息后提交审核,审核通过上架即可(https://dev.vivo.com.cn/appCreate

七、开放平台审核、Push服务审核

应用推送申请为自动审核,内容库审核通过上架后将同步到Vpush平台,平台会在1-2个工作日同步审核完成。

八、创建正式消息

方式一:接入《服务端API接口文档》创建推送

方式二:在运营后台创建消息

九、用户接收推送

vivo通知授权弹窗说明

基于开发者业务合规性与业务需求,保证用户友好使用体验,避免未经用户同意直接发送通知,或因用户不知道如何开启通知而影响后续使用。 vivo拟于2021年8月后发布的新机型上,将通知选择权交给用户,用户首次进入新安装应用时弹窗询问用户是否允许通知,新机型不再实行用户启动应用即成功订阅逻辑。

一、策略说明

通知选择权交给用户,在用户首次进入新安装的应用时,弹窗询问用户是否允许通知(以下简称“通知授权弹窗”)。

l  用户点击“允许”:应用通知、锁屏通知、悬浮通知、桌面角标都统一开启,应用具备推送通知的能力(请确保符合相关规则,不要滥用!)

l  用户点击“禁止”:应用通知、锁屏通知、悬浮通知、桌面角标都保持关闭,应用通知将不会被用户接收。

l  用户点击“更多设置”:跳转到应用的通知管理页面,进行详细设置,用户可以自由选择和组合以上通知的开关状态,做到精细化管理。

二、弹窗样式

三、FAQ

Q1、通知授权弹窗为什么会在我们隐私协议/权限申请弹出之前就出现了?是否符合相关管控规定?

通知授权弹窗是系统统一弹出,而隐私协议/权限申请是应用自行弹出的,每个应用每个版本的隐私协议/权限申请弹出时机都不同,系统无法识别,也无法逐一适配,因此统一在用户首次进入新安装的应用时就弹窗。后续我们会开放弹窗的接口,应用可进行调用并做好弹窗之间的冲突处理。通知授权弹窗询问并非获取用户权限及收集用户个人信息请求,不属于狭义定义范围中的“权限”,与相关管控规定暂无冲突。

Q2、这个弹窗的样式和文案,我们能自定义内容吗?

为保持用户对于通知管理的认知一致,暂不支持自定义弹窗内容。若应用有需要,可自行设计弹窗进行引导,需要符合设计规范、控制好弹出条件、频率、频次和最大次数等,保证良好的用户使用感受。

Q3、这个弹窗是每次进应用都弹么?

系统弹窗最多只弹出一次。应用被卸载后重新计数。

Q4、从哪个版本开始做实施该策略的?

X60系列作为试点实施了该策略,后续出货的新机型(即从2021年8月发布的新机型)都使用该策略。

Q5、是否违反工信部的权限管理要求?

“通知权限”独立于存储、读取通讯录等关键权限,并非获取用户权限及收集用户个人信息请求。

Q6、应用方需要做什么适配或接入吗?

无需适配,后续开放弹窗接口后,应用可进行调用并做好弹窗之间的冲突处理。若不调用则遵循系统弹出原则,统一在用户首次进入新安装的应用时就弹窗。

Q7、用户选择关闭拒绝后,还会再开启吗?

用户拒绝后,也可以在“设置”内通过系统消息开关设置开启。应用方可根据自身策略引导用户开启通知权限。

Q8、老机型以前是什么规则?后续是否变动?

策略只针对2021年8月后发布的新机型,老机型维持原有规则不变,即用户主动激活视为订阅成功开启通知,后续不会变动。

Q9、新老机型量级频控规则是否变动?

不变,新老机型依旧遵循运营消息量级默认为一倍订阅量,5条频控原则。系统消息量级默认一倍订阅量,不限制频控。

Q10、用户没有进行选择,直接按了返回或者home键,这个权限的是全部打开还是全部关闭呢?会继续出弹窗让用户选择么?

关闭,不会再弹出了

Q11、是vivo推送和应用自身push的通知开关状态都默认关闭了吗?

是的,用户首次进入应用时,弹窗询问用户是否允许通知

vivo推送产品说明

一.vivo推送简介

vivo推送(即Vpush)是vivo公司向开发者提供的消息推送服务,通过在云端与客户端之间建立一条稳定、可靠的长连接,为开发者提供向客户端应用实时推送消息的服务,支持百亿级的通知/消息推送,秒级触达移动用户。

开发者可以方便地通过嵌入SDK,调用API或者Web端进行可视化操作,实现对特定用户人群推送,大幅提升用户活跃度,有效唤醒沉睡用户,并实时查看推送效果。

二.产品优势

1.系统级通道

vivo推送在手机上的长连接由系统维护,能够充分的保障通知栏消息在vivo上的送达率。设备联网的情况下,有效推送的送达率能达到99.9%以上。

2.用户优质、流量丰富、赋能营销

拥有庞大的有活力、有潜力的优质用户,助力精细化优质应用推广、不断汇聚vivo全生态优质应用推广流量,满足日益增长的获客诉求、并通过强大个性化算法能力、完整营销闭环赋能智慧营销。

3.稳定、安全、高性能、快捷

支持每秒100w推送速度,亿级用户同时在线,稳定性好,安全性高,快速集成SDK,提供Web平台和API两种运营推送方式,有效提升运营效率。

4.全面的数据统计

推送平台提供包括APP数据、消息数据等多维度的统计,同时支持小时级实时数据,帮助开发者更好的掌握应用数据,助力精细化运营。

5.定时推送

开发者可以根据业务需求自定义消息推送时间,可以选择立即推送或指定时间推送。

6.在线诊断工具

vivo推送提供一站式服务能力,一套完备的调查工具可以辅助开发者自助查询设备与消息的对应关系与送达/在线情况,实时把控消息状态。

三.功能介绍

1.运营推送方式

vivo推送支持通知栏提醒消息类型,同时提供web平台和API两种运营推送方式。

① API推送

通过vivo推送提供的API接口,开发者可构建并发送消息。并提供个性化功能,包括获取统计数据、查询消息状态、获取失效数据等。

vivo推送官方提供了JAVA、PYTHON服务端SDK版本,如果无法满足需求,我们提供了http API,开发者可以自行进行封装调用,满足各种定制化的推送需求。

详细介绍请参见《服务端SDK文档》《服务端API接口文档》

② 推送运营平台

推送运营平台是vivo推送提供的管理和使用推送业务的一站式平台,通过运营平台开发者可以实现应用管理、消息下发、数据统计、消息追踪等功能。

推送运营平台网页版推送工具可以帮助开发者通过运营平台快速实现消息下发。支持通知栏消息消息推送,同时支持多种推送方式和个性化推送。

点击进入:推送运营平台

2.通知栏展示

消息通过vivo push系统通道下发,不需要应用驻留后台。客户端收到这类消息后,会直接在通知栏展现。

用户点击弹出通知后,客户端SDK会将消息中携带的数据传递给应用,由应用决定下一步的动作。 

通知栏消息展示效果如图所示,主要内容包括消息标题、摘要、应用图标、应用名称和时间,开发者可以自定义标题和摘要。

同时,针对每条消息开发者也可以单独定义是否响铃/振动(只对Android8.0以下)。

注: 在vivo push中,由于通知栏是由vivo服务框架弹出,因此图标均不可自定义,且部分版本不展示右侧小图标。

3.推送方式

vivo推送支持RegID、Alias、标签等消息发送方式。

① 基于 RegID的推送

RegID为vivo推送为每个设备上的每个app注册推送服务时生成的唯一标示。

当开发者需要给一个或多个具体的设备推送消息时,可以使用基于RegID的推送,将个性化的信息推送给指定的设备。这种方式适用于需要为每个用户订制个性化推送的场景。 

注:

• RegID是在客户端向vivo推送服务注册时,vivo推送服务端根据设备标识、AppID以及当前时间戳生成,因此能够保证每个设备上每个app对应的regID都是不同的。

• RegID在应用卸载或清除本地数据后重新卸载、14天不在网后又重新联网regid均不会变。

• RegID在如下几种情况下会被判断失效:

    A .  App卸载重装或者清除数据后重新注册,这种情况下会生成一个新的RegID,而老的RegID会失效

    B .  App调用了turnOffpush

    C .  在vivo上,App卸载时,如果能成功上报,则RegID会被判定失效

    D .  设备超过14天没有和vivo Push服务器建立长连接

② 基于 Alias的推送

alias是vivo推送提供的一种个性化设定, 开发者可以将用户在应用内的账号或其它用户唯一标识设定为用户设备RegID的别名,在推送中可以直接基于别名进行推送。

别名不仅方便开发者将推送与自有的账号系统进行关联,同时也避免了因需要保存设备RegID与自有帐号的对应关系而额外带来的开发和存储成本。 

注:

• alias与RegID(设备)一一对应,同一个alias不能对应多个RegID,alias对应的RegID以最后一次setalias对应的RegID为准

• alias失效的可能原因如下:主动调用unsetalias;alias对应的RegID已经失效

• alias只跟设备相关,所以请使用用户账号作为alias时,合理判断alias可能失效的情况

③ 基于标签的推送

对应用下已订阅vivo推送的设置了标签的用户进行推送。在推送消息时,开发者可以结合每条消息的内容和目标用户人群,选择所对应的标签,完成请求后,vivo推送推送服务会向所有打上这一标签的用户发送该消息,从而满足定向推送的需求,并提供标签管理功能。

四. 其他个性化功能

1. 定时推送

开发者可以根据业务需求自定义消息推送时间,可以选择立即推送或指定时间推送。

定时消息功能可以指定未来30天内任意时间作为消息下发时间。

定时消息在消息开始推送之前可以在“消息推送平台-推送设置-待发送消息”中取消。

2.自定义消息有效期

开发者可以根据自己的业务需求设置每条推送消息的有效期,推送的目标用户在消息有效期内网络在线就会收到消息。

消息有效期最长7天。如果应用没有单独设置一条消息的有效期,vivo推送的默认有效期是1天。 

3.自定义键值对

开发者可以自己输入一些自定义的键值对(key-value),在发送消息时传给客户端/服务端。客户端/服务端可以根据这些key-value可完成一些相应的操作。

4.自定义push提示声音

vivo提供Push通知铃声、震动、铃声+震动、无等提示方式,开发者可以自由控制推送消息到达时的提醒方式。

5.推送标题和内容支持添加emoji表情

开发者可在新建推送输入推送标题和内容时,插入emoji表情(分别最多不超过3个)以丰富推送内容,吸引用户点击了解推送内容。

6.AB test分组对比测试

vivo推送支持AB test分组对比测试,开发者可通过AB test分组对比测试为开发者提供精细化运营手段,通过AB test的结果由数据来做出决策,在运营中继续获得确定的用户增长。

vivo推送的AB test分组对比测试支持对比通知文案测试、对比用户群体测试、自动发送和手动发送以及独立的数据统计助力开发者的运营活动。

• 对比通知文案:向同类人群发送多个文案(上限为4个),筛选出最佳数据指标的文案进行正式组推送。

• 对比用户群体:将多个人群(上限为4个)发送一个文案,筛选出此文案最佳受众人群进行正式组推送。

• 发送形式:分为自动推送和手动推送

①自动推送:自动发送将会在选择的文案判别时间内收集数据,根据所选择的文案选择指标,在测试结果返回判断后自动发送最佳文案。

②手动推送:会将手动测试的结果保存在消息记录中,在消息记录中根据心仪数据继续手动发送。可选手动发送时间将从AB test测试组发送完成后开始计时三天,超过三天的手动发送AB test将不可继续手动发送。

• 数据统计:数据统计可在消息记录中实时查询,可同时观测测试组发送情况与正式组选择情况。实时转化、消息折损与推送时效将同步在AB test的消息记录中。

7.平缓推送

开启平缓推送功能,开发者可根据自身需要自行设定消息发送速度,使消息以均匀的速度送达用户设备,降低大量消息发送对服务器造成的压力和负担。

平缓推送支持每秒发送500-100000消息,打开开关默认速度为3000条/s

五.使用推送

1. 启用推送

登录vivo开放平台,注册开发者账号并创建APP审核通过之后,新建推送启用推送服务。详细介绍请参见《vivo推送使用指南》

2. 集成客户端SDK

vivo推送服务的客户端SDK集成非常简单,仅需一位工程师0.5天的时间即可完成客户端SDK的集成。 

《服务端SDK文档》

《客户端SDK集成指南

3. 推送统计

vivo推送支持推送数据实时统计功能,包括推送数据、APP数据等维度,帮助开发者更好的监控和分析业务现状。

六.常见问题

关于推送接入及后续使用的常见问题,可以参考《常见FAQ》

VIVO关于全面落实网络游戏适龄提示制度的通知

尊敬的各位开发者:

受深圳市新闻出版局委托,深圳市互联网文化市场协会将推进深圳市网络游戏企业全面落实网络游戏适龄提示制度,负责通知企业、沟通联系、解答疑问、收集统计落实情况、开展检查等具体工作。vivo作为主流手机厂商与应用分发平台,有责任和义务保障网络游戏适龄提示制度的推进及落实,建设更加绿色规范的网络游戏环境。现就有关工作事项进行如下通知,请各位开发者积极配合:

注:该通知仅限于深圳地区的开发者进行配合及整改。其他地区开发者朋友可参照标准自查并完善适龄提示相关内容,自觉履行未成年人保护责任。

第一项,通知落实

请各位开发者按照《未成年人网络游戏适龄提示》团体标准,对本公司在线运营的所有网络游戏产品及游戏宣传场景自查适龄提示应用情况。

具体包括:

1、在官方网站上的游戏购买或下载界面,以及游戏注册、登录或开始界面显著位置放置适龄提示标识;

2、在游戏的宣传视频、宣传海报或宣传广告以及其他宣传游戏的场景使用标识。

请各位深圳企业开发者朋友们尽快落实工作,并填写《深圳网络游戏产品落实适龄提示情况统计表》,发送至电子邮箱sica0755@qq.com(邮件名标注企业名称)。

如各企业在对照标准落实适龄提示的过程中有具体疑问,可扫描如下二维码进行咨询:

第二项,组织学习

为确保深圳企业开发者们落实质量,深圳市互联网文化市场协会将适时组织举办2场《未成年人网络游戏适龄提示》团体标准宣讲活动,届时将邀请行业专家对适龄提示标识使用要求、评价准则等进行讲解。宣讲具体时间协会将另行通知,请各位开发者积极关注【vivo开放平台】的最新通知。

第三项,专项检查

从今年11月开始,深圳互联网文化市场协会将通过线上检查、上门走访等方式开展适龄提示落实情况专项检查。对落实不到位或整改不到位的深圳企业,将上报至深圳市新闻出版局。

以上为深圳市互联网文化协会关于全面落实网络游戏适龄提示制度的通知的具体内容,请各位开发者积极配合进行自查和整改。相关指导文件及表格请点击附件进行下载。

附件1: 关于全面落实网络游戏适龄提示制度的通知

附件2:《未成年人网络游戏适龄提示》团体标准

附件3: 深圳网络游戏产品落实适龄提示情况统计表

附件4: 适龄提示标识素材

未成年人网络游戏适龄提示

1. 范围

本标准规定了未成年人网络游戏适龄提示标识以及标识的使用场景和使用说明。

本标准适用于网络游戏的开发、运营等相关工作。

2. 范围规范性引用文件

下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件,仅所注日期的版本适用于本文件。凡是不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件。

GB/T32626—2016 信息技术 网络游戏 术语

中华人民共和国未成年人保护法(2020修订)

3. 术语和定义

下列术语和定义适用于本文件。

3.1  网络游戏 online game

通过计算机网络、移动通信网等网络提供的游戏产品和服务。

[来源:GB/T32626—2016,2.8]

3.2  未成年人 minor

未满18周岁的公民。

[来源:中华人民共和国未成年人保护法(2020修订),第一章第二条]。

3.3  适龄提示 age labeling

针对未成年人网络游戏适用年龄段的提示信息,包含适龄提示标识和提示说明。

4. 适龄提示组成

未成年人网络游戏适龄提示由适龄提示标识及提示说明组成。

为了给未成年游戏用户和其监护人简明的游戏适龄提示,各游戏企业应根据不同年龄段未成年人的特点、综合考虑适龄的游戏类型与游戏功能,对游戏进行评估,确定游戏适用的年龄段,选择对应的游戏适龄提示标识和提示说明。

5. 适龄提示标识及使用

5.1  适龄划分

依据我国现行法律法规,综合考虑心理学、教育学和青少年健康等相关理论和研究成果,本标准将未成年人游戏适龄的范围划分为3个阶段,如表1所示。

                                                                          表1  游戏适龄范围

第一阶段范围第二阶段范围第三阶段范围
8周岁(含)以上12周岁(含)以上16周岁(含)以上

注1:未满8周岁未成年人不建议使用网络游戏。

注2:18周岁(含)以上成年人本标准不做适龄提示。

5.2  提示标识

网络游戏适龄提示标识如图1~3所示,其中数字表示适龄范围,CADPA为中国音像与数字出版协会英文缩写。

1)适用于8周岁(含)以上用户的游戏,使用8+标识,如图1所示。

2)适用于12周岁(含)以上用户的游戏,使用12+标识,如图2所示。

3)适用于16周岁(含)以上用户的游戏,使用16+标识,如图3所示。

5.3  使用场景

应在如下场景中使用适龄提示标识:

1)在官方网站上的游戏购买或下载界面;

2)游戏注册/登录界面;

3)若游戏无注册/登录界面,则应在游戏开始界面显著位置放置适龄提示标识;

宜在游戏的宣传视频、宣传海报或宣传广告以及其他宣传游戏的场景使用标识。

5.4  使用要求

适龄提示标识应从中国音像与数字出版协会官方网站www.cadpa.org.cn或者www.cgigc.com.cn下载,并遵循以下使用要求:

1)适龄提示标识与游戏界面的背景颜色应明显区分;

2)适龄提示标识应放置在游戏注册/登录界面或宣传海报等静态界面的显著位置,宜放置在游戏名称附近,不可遮挡;

3)游戏宣传视频内,适龄提示标识出现时长不应少于3秒;

4)游戏静态界面中,点击适龄提示标识应能够展开或跳转至包含适龄提示用语的页面;

5)主机游戏在实体产品或游戏商店的显著位置放置适龄提示标识;

6)微信小游戏在加载页面或游戏主界面显著位置放置适龄提示标识;

7)对适龄提示标识的大小不作具体限制,但提示标识的最小边长不小于屏幕最小边长的1/10;

8)游戏版本更新时,适龄提示应同步更新。

6. 适龄提示说明和使用

6.1  适龄提示说明用语要求

适龄提示说明用语参考附录A给出,内容应包含:

1)游戏概括性描述,包括游戏特征、类型、适用年龄及在家长监护下使用游戏的建议;

2)游戏内容描述,包括游戏剧情、玩法、社交等关键内容;

3)实名认证信息、对未成年人游戏充值限制及时长限制,内容应符合《中华人民共和国未成年人保护法(2020修订)》《关于进一步严格管理切实防止未成年人沉迷网络游戏的通知》《关于开展文娱领域综合治理工作的通知》等要求。游戏中如有玩法或内容根据相关规定对未成年用户进行技术限制,应加以注明。

4)适龄提示用语可包含正向功能说明,应根据游戏内容对促进功能合理描述,避免过度夸大功能的作用和数量。

6.2  适龄提示说明用语使用场景及要求

游戏企业应根据游戏实际情况选择适龄提示用语,并在如下场景的显著位置显示:

1)如具有官网,应在官方网站上的游戏购买或下载界面显著位置显示;

2)点击适龄提示标识后展开或跳转的页面显示;

3)用户首次注册时应展示适龄提示用语。

附录 A(资料性附录)

适龄提示评价准则

A.1 适龄提示心理准则

从心理学的角度,给出不同年龄段未成年人行为活动中的心理特征,以此为依据对网络游戏适龄提示给予相应的科学指导。具体内容如表A.1所示。

                                                                                                      表A.1  适龄提示心理特征

范围情感认知社会化特征及类型

自我评价水平较弱;情绪管控能力弱;意志力相对薄弱,注意力稳定性较弱。独立性和自制力弱,易受外界干扰。具备基本认知能力,开始从具体形象思维逐步过渡到抽象逻辑思维,出现辩证逻辑思维的萌芽。抽象、比较和分类能力有所发展,特别是思维的敏捷性、灵活性深刻性和独创性开始发展,但思维发展具有不平衡性。具备一定的是非判断能力,道德观开始构建,但受到外部、具体的情境的制约,社会认知处于起步阶段。社会自我的意识逐渐萌发,对社会关系产生初步认识。建立同伴关系和友谊,社会交往能力得到初步锻炼,合作意识、尝试团体协作、同伴交往能力开始形成。适合8周岁以上的未成年人使用的游戏,玩法简单、单局耗时短。如简单的休闲益智类、解谜类、模拟养成/经营类、音乐舞蹈类和塔防类游戏等。

开始进行现实的规划和探索思考,对事物的反应更灵敏,有追求冒险和刺激的心理,但自我控制力较弱。处于身心发展不平衡时期。以基于经验的抽象逻辑思维为主,但是水平相对较低。辩证思维开始发展,但是具有一定的表面性和偏颇性,容易产生自我中心的思维观念。自我意识发展的飞跃期,出现逆反的心理和意识,表现出复杂矛盾的情绪变化。内心渴望倾吐烦恼、交流思想并保守秘密的渠道。社会交往更加聚焦,朋友关系日益重要。适合12周岁以上的未成年人使用的游戏,玩法相对复杂,需投入一定的时间和精力。如跑酷竞速类、角色扮演类、沙盒类、音乐舞蹈类、体育类、策略类和动作冒险类游戏等。

身心发展日益成熟,情感需求向成人趋同,对生活充满美好憧憬。同时思想敏感,自我评价具有起伏性,情绪易波动。生理和心理发展均趋于成熟稳定,感知觉、观察能力、记忆能力和想象能力不断完善,抽象逻辑思维能力逐渐增强,特别是认识、分析和解决问题的能力。自我意识高度发展,高度关心自我个性成长,自我评价偏高,自尊心和道德意识强烈。对自己、他人和社会事件具有独立思考和判断标准。团队合作意识强,渴望在集体中展现自我价值,期待社会赞许。适合16周岁以上的未成年人使用的游戏,玩法复杂,投入精力较多,游戏流程耗时较长。如内容操作较复杂的角色扮演类、动作冒险类、射击类(战术竞技类)、MOBA、策略类、卡牌类和牌类等游戏。

A.2 适龄提示产品准则

网络游戏适龄提示以未成年人的心理特征以及心理需求为基础,对游戏的特征和类型、内容表现、促进功能进行评价,以帮助社会了解游戏的内容及特点。具体要求如表A.2所示。

                                                                                                      表A.2  适龄游戏内容要求

标识内容表现促进功能

适用于8周岁以上未成年人的游戏,对游戏内容有以下要求:1)内容要素:游戏背景、情节、角色等设计简单友好,文字和语法简单易懂,无复杂的故事背景和人物关系。可存在积极美好的想象和虚构,可存在需要自我选择、责任感及成功冒险的故事情节,有正义及快乐的结局。无基于历史和现实事件的改编,不会与现实生活相混淆。游戏可以促进同伴关系,存在少量简单的团队合作或好友助力内容。2)画面表现:游戏画面和美术设计为简单轻松的卡通、手绘风格。3)音效表现:
游戏音效欢快活泼或舒缓悠扬。4)竞技和对抗:竞技和对抗玩法基于简单的思维判断或肢体操作。竞技或对抗内容以卡通或幻想的形式出现。游戏存在剧情需要的少量对抗设置,没有体现具体对抗行为和结果的视听内容,不会与现实生活相混淆。竞技内容以培养竞争概念和勇气为主要目的,内容可含体育竞技、棋类竞技。5)社交系统:游戏中不存在基于文字、语音、图片等自由交流的陌生人社交系统,可存在简单的好友系统。
适用于8周岁以上未成年人的游戏宜具有下列功能:1)知识学习:可包含亲子互动、入门知识、学科启蒙知识等内容。2)技能与行为训练:可培养玩家简单的日常生活技能。3)认知促进:能够辅助培养玩家手眼协调能力、观察力、想象力等。4)情感与审美:可辅助玩家形成正向积极的情感表达、形成基础的审美能力,或帮助玩家初步认识中华传统文化等。5)社会化发展:有助于玩家形成简单的社交能力,初步认识社会主义核心价值观等。

适用于12周岁以上未成年人的游戏,对游戏内容有以下要求:1)内容要素:游戏背景、情节、角色等设计丰富多彩。可存在清晰完整的故事背景和适量的人物关系;可存在积极美好的想象和虚构;可存在生存奋斗的故事情节;可存在部分基于历史和现实事件的改编,但不会与现实生活相混淆。游戏中可有少量团队任务,需要组队完成。2)画面表现:游戏画面和美术设计应丰富美好、色彩鲜明。可为动漫或56风格,不宜有写实的对抗画面。3)音效表现:
可根据游戏情节增加不同风格的音效,但整体以较欢快活泼或舒缓悠扬为主。4)竞技和对抗:竞技和对抗玩法基于一定难度的思维判断或肢体操作鼓励玩家通过思考和训练达成目标。游戏存在少量与情节相关的对抗内容,可存在以对抗为主的竞技比赛,但对抗内容以非写实的形式出现,不会与现实生活相混淆。不含宣扬、美化不当对抗行为的内容。5)社交系统:游戏中可存在基于文字、语音、图片等自由交流的陌生人社交系统,但社交系统的管理应遵循相关法律法规。
适用于12周岁以上未成年人的游戏宜具有下列功能:1)知识学习:包含初、中级基础知识、学科入门知识等内容。2)技能与行为训练:可培养玩家自理能力和日常学习能力。3)认知促进:有助于玩家锻炼逻辑思维能力、辨别能力、推理判断能力、注意广度与分配能力,提高手眼协调能力和反应能力等。4)情感与审美:可引导玩家建立自信,有助于玩家开阔眼界、提升基础审美能力及了解中华传统文化等。5)社会化发展:有助于玩家提升沟通能力、建立团队合作意识,学习恰当处理自己与环境、他人的关系。可培养玩家品德,帮助玩家深入了解社会主义核心价值观。

适用于16周岁以上未成年人的游戏,对游戏内容有以下要求:1)内容要素:游戏背景、情节、角色等设计丰富多彩且富有个性,可含有宏大的故事背景和丰富的人物关系。可存在合理的想象和虚构,有适量基于历史和现实事件的改编,但不会与现实生活相混淆。游戏内容对玩家逻辑思维、团队协作能力有一定要求。游戏中可存在较多大型团队任务或团队比赛。2)画面表现:游戏画面和美术设计多样化,可为3D写实风格,但不会与现实生活相混淆。3)音效表现:
游戏中有丰富的音效,以烘托游戏氛围。4)竞技和对抗:竞技和对抗玩法可基于较高难度的思维判断或肢体操作,鼓励玩家提升和挑战自我。游戏以对抗为主要玩法,可存在大型对抗竞技比赛,竞争内容可以较写实的形式出现(对抗双方均为写实的人类形象或人形生物且对抗展示了接近真实的击打效果),但不会与现实生活相混淆。游戏允许用户之间的对抗行为,不含宣扬、美化不当对抗行为的内容。5)社交系统:游戏中可存在基于文字、语音、图片等自由交流的陌生人社交系统,但社交系统的管理应遵循相关法律法规。
适用于16周岁以上未成年人的游戏宜具有下列功能:1)知识学习:包含中、高级知识体系、较复杂的学科知识等。可能包含大量课本外的文学、科学、历史、地理等知识,帮助玩家扩充知识面。2)技能与行为训练:包含全面的日常生活与学习技能的指导和训练,或可扩充训练玩家专业技能等。3)认知促进:有助于玩家锻炼独立思考和分析解决问题能力、进一步提高逻辑思维能力、推理判断能力、手眼协调和快速反应能力等。4)情感与审美:可引导玩家建立自信,鼓励玩家提升和挑战自我。有助于玩家开阔眼界、进一步提升审美能力,或深入传播中华传统文化等。5)社会化发展:提升玩家责任感,维持良好的社群关系。可传播和巩固社会主义核心价值观。

游戏适龄实施细则

1. 适龄分级划分

vivo游戏适龄按年龄段划分为4个阶段,请根据您的产品如实选择适龄分级,具体请参照《未成年人网络游戏适龄提示》团体标准

第一阶段范围第二阶段范围第三阶段范围第四阶段范围
8周岁(含)以上12周岁(含)以上16周岁(含)以上18周岁(含)以上

2. 适龄适用范围

vivo内容库上架APK游戏(不包含小游戏)。

3. 适龄审核内容

① 游戏登录/开始界面需添加适龄提示,请确保适龄提示信息的清晰可见,其中8+、12+、16+游戏需使用对应适龄提示标识,18+游戏使用文字额外进行说明;

8周岁(含)以上12周岁(含)以上16周岁(含)以上18周岁(含)以上

8+标识

12+标识

16+标识

为维护未成年人健康上网环境,本游戏暂不支持实名认证18岁以下的用户登录体验
 18+文字说明

② 开发者开平所填写适龄分级字段需与游戏内适龄提示保持一致。

4. 开发者责任及vivo权限

① 开发者需提供真实、准确的游戏适龄分级信息并进行核对,若游戏更新及游戏内容发生相应变化,需及时调整产品适龄信息,开发者对所选游戏适龄分级信息负全责;

② vivo有权依照适龄分级条例进行相应核查,若vivo收到用户反馈游戏适龄信息与游戏内容不符且情况属实,vivo有权以下架、冻结等方式对游戏进行处理。

附件:适龄提示标识素材