卡券-小程序打通


上一篇 : 卡券事件推送 下一篇: 微信礼品卡



目录

1.小程序内领取卡券

2.小程序内查看卡券

3.小程序开卡组件

4.卡券内跳转小程序


小程序内领取卡券

场景介绍

商家在小程序内进行营销活动时,可以将卡券作为奖品、优惠兑换凭证发放给用户,用户领取到卡包后可以快捷地出示使用并进行核销。

同时,某些票务类的小程序也可以将用户购买后的票券供用户添加至卡包,方便用户出示使用。

步骤

1.开发者须有一个有卡券权限的公众号和认证后的小程序账号;

2.开发者须申请一个第三方平台账号,并将小程序和公众号绑定在同一个第三方账号下,关于第三方平台的介绍请参照:微信开放平台

3.阅读卡券接口说明创建卡券接口,创建卡券并获得card_id;

4.在小程序内调用wx.addcard接口并处理领取成功的回调;

5.在第三步中获取到的card_id、code(加密code)请求解码code接口获取真实的code;

6.记录用户小程序内的openid、用户领取的code以及card_id;

7.处理卡券领取事件,记录用户在公众号内的openid、以及用户领取的code以及card_id。

接口说明

wx.addcard接口请参考:wx.addcard

注意事项

1.wx.addcard接口中涉及的签名中的api_ticket须传入创建该卡券公众号获取到的ticket;

2.用户领取卡券后,会有领取卡券事件推送至开发者服务器,开发者须进行处理,详细请见卡券事件通知

3.开发者可以通过outer_str判断用户的领券来源;

4.该功能仅支持1.1.0版本以及以上的基础库版本,小程序内须做版本判断并对低版本进行兼容。


小程序内查看卡券

场景介绍

开发者可以通过调用该接口允许用户在小程序内查看、出示自己的微信卡券。

步骤

1.开发者须在用户进入小程序时,获取用户已经领取到的卡券的card_id和code(真实code); 2.调用wx.opencard打开用户某张卡券供用户查看、使用。

接口说明

wx.opencard接口请参考:wx.opencard

注意事项

1.目前卡券领取后会自动返回小程序页面,若开发者鼓励用户领卡后继续在卡面上进行下一步操作,须在wx.addcard的函数回调内调用wx.opencard;

2.wx.addcard成功后返回的参数中code为加密字段,须解密后才能调用wx.opencard,详情请见[解码code接口


小程序开卡组件

场景介绍

开发者可以在小程序里面开发自己的会员模块,并将开卡环节嵌入其中,微信卡券为小程序内会员开卡提供了“开卡组件功能”。

用户在小程序内进入开卡组件时,可以快速拉取到用户之前在微信开卡填写的资料并预填,用户可以做到“一键开卡”。

对商户而言,开卡组件集“开卡注册”和“添加至卡包”于一体,快捷开卡的同时可以省掉手机验证等环节,提高开卡率。

目前开卡组件分为跳转型开卡组件和非跳转型开卡组件。

注意:

1.小程序调用开卡组件须公众号具有微信卡券功能,详情请见:微信卡券说明

2.开发者须先了解卡券开发的基本知识后调用,详情请见:微信卡券接口说明

步骤

跳转型一键开卡步骤

  1. 创建一张会员卡会员卡,会员卡的激活方式选择“wx_activate":true,"wx_activate_after_submit" : true,并在activate_app_brand_user_name、activate_app_brand_pass传入激活小程序页面的相关信息,并获得card_id,详情见:创建会员卡接口

  2. 设置用户开卡时填写的开卡字段,分必填和选填,详情见:设置开卡字段接口

  3. 获取开卡组件所需的参数;

  4. 判断新老用户、客户端版本决定是否要调用开卡插件接口;

  5. 调用开卡插件供用户开卡,并处理开卡插件的回调;

  6. 获取用户开卡资料并激活用户的会员卡;

具体流程如图:

0 (1).jpg

非跳转型一键开卡步骤

  1. 创建一张会员卡会员卡,会员卡的激活方式选择“wx_activate":true,"wx_activate_after_submit" : false,并获得card_id,详情见:
    创建会员卡接口

  2. 设置用户开卡时填写的开卡字段,分必填和选填,详情见:设置开卡字段接口

  3. 获取开卡组件所需的参数;

  4. 判断新老用户、客户端版本决定是否要调用开卡插件接口;

  5. 调用开卡插件供用户开卡,并处理开卡插件的回调;

  6. 获取用户开卡资料;

0.jpg

接口说明

接口1:获取开卡插件参数

接口说明

开发者可以通过该接口获取到调用开卡插件所需的参数。

请求参数说明

参数 参数说明
access_token 创建卡公众号的token
JSON 请求数据
URL https://api.weixin.qq.com/card/membercard/activate/geturl?access_token= ACCESS_TOKEN
{ "card_id" : "pbLatji6o5g7hJh8Otuvux4y1ty0", "outer_str" : "123" }
参数 是否必填 参数说明
card_id 会员卡的card_id
outer_str 渠道值,用于统计本次领取的渠道参数
{   "errcode": 0,   "errmsg": "ok",   "url": "https://mp.weixin.qq.com/bizmall/activatemembercard?    action=preshow&&enxxxxxxx=MjM5Mzc0OTEwMA%3D%3D#wechat_redirect" }

返回参数说明

参数 参数说明
errcode 错误码
errmsg 错误信息,用于定位错误原因
url 返回的url,内含调用开卡插件所需的参数

注意事项 1.本接口返回的参数须原封不动地填入开卡插件接口,须做urldecode操作;

接口2:小程序内打开开卡插件的接口

接口说明

1.开发者通过该接口可以在自己的小程序内打开开卡插件;

2.该接口为小程序接口,开发者须先了解小程序接口的调用方法:详情见:卡券事件通知

3.基础库 1.3.0 开始支持,低版本需做兼容处理

4.iOS 微信客户端 6.5.9 版本开始支持,Android 客户端即将在 6.5.10 版本开始支持,请先使用 iOS 客户端进行调试

打开同一公众号下关联的另一个小程序。

OBJECT参数说明:

参数名 类型 必填 说明
appId String 要打开的官方插件的appid,固定为wxeb490c6f9b154ef9,不可更改
extraData Object 需要传递给目标小程序的数据,目标小程序可在 App.onLaunch(),App.onShow() 中获取到这份数据。
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数名 类型 说明 errMsg String 调用结果

示例代码:

wx.navigateToMiniProgram({   appId: ‘wxeb490c6f9b154ef9’, // 固定为此appid,不可改动   extraData: data, // 包括encrypt_card_id outer_str biz三个字段,须从step3中获得的链接中获取参数   success: function() {    },   fail: function() {   },   complete: function() {   } })

返回说明

在App.onShow里判断从会员开卡小程序返回的数据data

  1. 判断data.referrerInfo.appId是否为开卡小程序appId 'wxeb490c6f9b154ef9',如果不是则中止判断

  2. 判断是否有data.referrerInfo.extraData是否有数据,如果没有,表示用户未激活直接左滑/点返回键返回,或者用户已经激活

  3. 若用户激活成功,可以从data.referrerInfo.extraData中获取activate_ticket card_id code参数用于下一步操作

Bug & Tip tip: 在开发者工具上调用此 API 并不会真实的跳转到另外的小程序,但是开发者工具会校验本次调用跳转是否成功详情 tip: 开发者工具上支持被跳转的小程序处理接收参数的调试

接口3:获取用户开卡时提交的信息(跳转型开卡组件)

接口说明

开发者可以通过该接口获取到用户开卡时填写的字段值。

请求参数说明

参数 参数说明
access_token 创建卡公众号的token
JSON 请求数据
URL https://api.weixin.qq.com/card/membercard/activatetempinfo/get?access_token=TOKEN
{     "activate_ticket" : "abcdefg"         }
参数 是否必填 参数说明
activate_ticket 跳转型开卡组件开卡后回调中的激活票据,可以用来获取用户开卡资料
{
    "errcode": 0,
    "errmsg": "ok",
    "info": {
        "common_field_list": [
            {
                "name": "USER_FORM_INFO_FLAG_MOBILE",
                "value": "15*****518"
            },
            {
                "name": "USER_FORM_INFO_FLAG_NAME",
                "value": "HK"
            },
            {
                "name": "USER_FORM_INFO_FLAG_EDUCATION_BACKGROUND",
                "value": "研究生"
            }
        ],
        "custom_field_list": []
    }
}

返回参数说明

类型 描述
参数名 说明
errcode 错误码,0为正常
errmsg 错误信息
info 会员信息
custom_field_list 开发者设置的会员卡会员信息类目,如爱好。
name 会员信息类目名称
value 会员卡信息类目值,比如等级值等
value_list 填写项目为多选时的返回
value_list 填写项目为多选时的返回
common_field_list 官方定义的信息类目

common_field_id_list,支持开发者使用以下选项类型

参数 说明
USER_FORM_INFO_FLAG_MOBILE 手机号
USER_FORM_INFO_FLAG_SEX 性别
USER_FORM_INFO_FLAG_NAME 姓名
USER_FORM_INFO_FLAG_BIRTHDAY 生日
USER_FORM_INFO_FLAG_IDCARD 身份证
USER_FORM_INFO_FLAG_EMAIL 邮箱
USER_FORM_INFO_FLAG_LOCATION 详细地址
USER_FORM_INFO_FLAG_EDUCATION_BACKGRO 教育背景
USER_FORM_INFO_FLAG_INDUSTRY 行业
USER_FORM_INFO_FLAG_INCOME 收入
USER_FORM_INFO_FLAG_HABIT 兴趣爱好
  • 注意事项 1.本接口仅跳转型开卡组件可以调用,非跳转型的开卡组件回调中不含activate_ticket

接口4:获取用户开卡时提交的信息(非跳转型开卡组件)

接口说明

开发者可以通过该接口获取到用户开卡时填写的字段值。

请求参数说明

参数 参数说明
access_token 创建卡公众号的token
JSON 请求数据
URL https://api.weixin.qq.com/card/code/get?access_token=TOKEN
{     "card_id" : "abcdefg",     "code" : "abcdefg"         }
参数 是否必填 参数说明
card_id 卡券id,非自定义code类型会员卡不必填写
code 会员卡的code
  • 返回数据

{
    "errcode": 0,
    "errmsg": "ok",
    "openid": "obLatjjwDxxxxdoGIdwNqRXw",
    "nickname": "Fourier",
    "membership_number": "316510891298",
    "bonus": 460,
    "sex": "MALE",
    "user_info": {
        "common_field_list": [
            {
                "name": "USER_FORM_INFO_FLAG_MOBILE",
                "value": "1552xxxx8888"
            },
            {
                "name": "USER_FORM_INFO_FLAG_NAME",
                "value": "微信"
            }
        ],
        "custom_field_list": []
    },
    "user_card_status": "NORMAL"
}
参数名 说明
errcode 错误码,0为正常
errmsg 错误信息
openid 用户在本公众号内唯一识别码
nickname 用户昵称
bonus 积分信息
balance 余额信息
sex 用户性别
user_info 会员信息
custom_field_list 开发者设置的会员卡会员信息类目,如爱好。
common_field_list 官方定义的信息类目,如积分。
name 会员信息类目名称
value 会员卡信息类目值,比如等级值等
user_card_status 当前用户会员卡状态,NORMAL 正常 EXPIRE 已过期 GIFTING 转赠中 GIFT_SUCC 转赠成功 GIFT_TIMEOUT 转赠超时 DELETE 已删除,UNAVAILABLE 已失效

common_field_id_list,支持开发者使用以下选项类型

参数 说明
USER_FORM_INFO_FLAG_MOBILE 手机号
USER_FORM_INFO_FLAG_SEX 性别
USER_FORM_INFO_FLAG_NAME 姓名
USER_FORM_INFO_FLAG_BIRTHDAY 生日
USER_FORM_INFO_FLAG_IDCARD 身份证
USER_FORM_INFO_FLAG_EMAIL 邮箱
USER_FORM_INFO_FLAG_LOCATION 详细地址
USER_FORM_INFO_FLAG_EDUCATION_BACKGRO 教育背景
USER_FORM_INFO_FLAG_INDUSTRY 行业
USER_FORM_INFO_FLAG_INCOME 收入
USER_FORM_INFO_FLAG_HABIT 兴趣爱好

接口5:激活用户领取的会员卡(跳转型开卡组件)

接口说明

开发者可以通过该接口获取到用户开卡时填写的字段值。

请求参数说明

参数 参数说明
access_token 创建卡公众号的token
JSON 请求数据
URL https://api.weixin.qq.com/card/membercard/activate?access_token=TOKEN
{
    "init_bonus": 100,
    "init_bonus_record":"旧积分同步",
    "init_balance": 200,
    "membership_number": "AAA00000001",
    "code": "12312313",
    "card_id": "xxxx_card_id",
    "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
    "init_custom_field_value1": "xxxxx"
}
参数 是否必填 类型 描述
membership_number string(20) 会员卡编号,由开发者填入,作为序列号显示在用户的卡包里。可与Code码保持等值。
code string(20) 领取会员卡用户获得的code
card_id string(32) 卡券ID,自定义code卡券必填
background_pic_url string(128) 商家自定义会员卡背景图,须 先调用上传图片接口将背景图上传至CDN,否则报错,卡面设计请遵循微信会员卡自定义背景设计规范
activate_begin_time unsigned int 激活后的有效起始时间。若不填写默认以创建时的 data_info 为准。Unix时间戳格式。 activate_end_time 否 unsigned int 激活后的有效截至时间。若不填写默认以创建时的 data_info 为准。Unix时间戳格式。
init_bonus int 初始积分,不填为0。 init_bonus_record
init_balance int 初始余额,不填为0。
init_custom_field_value1 string(12) 创建时字段custom_field1定义类型的初始值,限制为4个汉字,12字节。
init_custom_field_value2 string(12) 创建时字段custom_field2定义类型的初始值,限制为4个汉字,12字节。
init_custom_field_value3 string(12) 创建时字段custom_field3定义类型的初始值,限制为4个汉字,12字节。

返回数据

{
    "init_bonus": 100,
    "init_bonus_record":"旧积分同步",
    "init_balance": 200,
    "membership_number": "AAA00000001",
    "code": "12312313",
    "card_id": "xxxx_card_id",
    "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
    "init_custom_field_value1": "xxxxx"
}
参数名 说明
errcode 错误码,0为正常
errmsg 错误信息

注意事项

  • 新老会员判断:若用户已领取微信会员卡,开发者可以通过获取用户信息接口获取到用户的unionid,用户授权登录小程序后可以关联用户之前的会员账户;

  • 新老版本判断:开发者对会员开卡须设计两套流程,iOS 6.5.9 &Android 6.5.10及其以上微信版本可以调用开卡组件,低版本须开发小程序自己的注册页面,用户注册完成后领取会员卡即可


卡券内跳转小程序

场景介绍

商户创建卡券时可以将卡、券内的服务入口设置进入小程序服务。

步骤

1.开发者须将小程序绑定在公众号下,绑定说明请见绑定公众号与小程序

2.创建卡券,并将卡内的cell设置小程序对应的path;

3.处理跳转小程序时获取到的信息;

接口说明

  • 创建会员卡

{ "card": {
    "card_type": "MEMBER_CARD",
    "member_card": {
        "base_info": {
            "custom_url_name": "立即使用",
            "custom_url": "http://www.qq.com",
            "custom_app_brand_user_name": "gh_86a091e50ad4@app",
            "custom_app_brand_pass":"API/cardPage",
            "custom_url_sub_title": "6个汉字tips",
            "promotion_url_name": "更多优惠",
          "promotion_url": "http://www.qq.com",
            "promotion_app_brand_user_name": "gh_86a091e50ad4@app",
            "promotion_app_brand_pass":"API/cardPage"
       }
        }
}
字段名 字段描述 字段示例
custom_app_brand_user_name 自定义使用入口跳转小程序的user_name,格式为原始id+@app gh_86a091e50ad4@app
custom_app_brand_pass 自定义使用入口小程序页面地址 API/cardPage
center_app_brand_user_name 小程序的user_name gh_86a091e50ad4@app
center_app_brand_pass 自定义居中使用入口小程序页面地址 API/cardPage
promotion_app_brand_user_name 小程序的user_name gh_86a091e50ad4@app
promotion_app_brand_pass 自定义营销入口小程序页面地址 API/cardPage
activate_app_brand_user_name 小程序的user_name, gh_86a091e50ad4@app
activate_app_brand_pass 激活小程序页面地址 API/cardPage
custom_field1、custom_field2 custom_field3 会员卡顶部的信息类目字段,包含以下两个字段
app_brand_user_name 自定义信息类目小程序user_name,格式为原始id+@app gh_86a091e50ad4@app
app_brand_pass 自定义信息类目小程序的页面路径 API/cardPage
custom_cell1、custom_cell2 会员卡自定义入口,包含以下两个字段
app_brand_user_name 自定义入口小程序user_name,格式为原始id+@app gh_86a091e50ad4@app
app_brand_pass 自定义入口小程序的页面路径 API/cardPage
bonus_app_brand_user_name 积分信息类目对应的小程序 user_name,格式为原始id+@app gh_86a091e50ad4@app
bonus_app_brand_pass 积分入口小程序的页面路径 API/cardPage
balance_app_brand_user_name 余额信息类目对应的小程序 user_name,格式为原始id+@app gh_86a091e50ad4@app
balance_app_brand_pass 余额入口小程序的页面路径 API/cardPage

*需调用卡券更新接口将相应小程序页面更新至对应跳转外链结构体中,原跳转H5字段保留。

  • 获取跳转参数

从卡券跳转小程序后,开发者可以通过apponshow的query中或取到发起跳转的card_id、encrypt_code和用户的公众号openid,开发者须调用解码code接口将encrypt_code解码为真实code。


上一篇 : 卡券事件推送 下一篇: 微信礼品卡