一、生成带参数的二维码
为了满足用户渠道推广分析和用户帐号绑定等场景的需要,公众平台提供了生成带参数二维码的接口。使用该接口可以获得多个带不同场景值的二维码,用户扫描后,公众号可以接收到事件推送。
目前有2种类型的二维码:
1、临时二维码,是有过期时间的,最长可以设置为在二维码生成后的30天(即2592000秒)后过期,但能够生成较多数量。临时二维码主要用于帐号绑定等不要求二维码永久保存的业务场景
2、永久二维码,是无过期时间的,但数量较少(目前为最多10万个)。永久二维码主要用于适用于帐号绑定、用户来源统计等场景。
用户扫描带场景值二维码时,可能推送以下两种事件:
如果用户还未关注公众号,则用户可以关注公众号,关注后微信会将带场景值关注事件推送给开发者。
如果用户已经关注公众号,在用户扫描后会自动进入会话,微信也会将带场景值扫描事件推送给开发者。
获取带参数的二维码的过程包括两步,首先创建二维码ticket,然后凭借ticket到指定URL换取二维码。
创建二维码ticket
每次创建二维码ticket需要提供一个开发者自行设定的参数(scene_id),分别介绍临时二维码和永久二维码的创建二维码ticket过程。
临时二维码请求说明
http请求方式: POST
URL: https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=TOKENPOST数据格式:json
POST数据例子:{"expire_seconds": 604800, "action_name": "QR_SCENE", "action_info": {"scene": {"scene_id": 123}}}
或者也可以使用以下POST数据创建字符串形式的二维码参数:
{"expire_seconds": 604800, "action_name": "QR_STR_SCENE", "action_info": {"scene": {"scene_str": "test"}}}
永久二维码请求说明
http请求方式: POST
URL: https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=TOKENPOST数据格式:json
POST数据例子:{"action_name": "QR_LIMIT_SCENE", "action_info": {"scene": {"scene_id": 123}}}
或者也可以使用以下POST数据创建字符串形式的二维码参数:
{"action_name": "QR_LIMIT_STR_SCENE", "action_info": {"scene": {"scene_str": "test"}}}
参数说明
参数 |
说明 |
expire_seconds |
该二维码有效时间,以秒为单位。 最大不超过2592000(即30天),此字段如果不填,则默认有效期为30秒。 |
action_name |
二维码类型,QR_SCENE为临时的整型参数值,QR_STR_SCENE为临时的字符串参数值,QR_LIMIT_SCENE为永久的整型参数值,QR_LIMIT_STR_SCENE为永久的字符串参数值 |
action_info |
二维码详细信息 |
scene_id |
场景值ID,临时二维码时为32位非0整型,永久二维码时最大值为100000(目前参数只支持1--100000) |
scene_str |
场景值ID(字符串形式的ID),字符串类型,长度限制为1到64 |
返回说明
正确的Json返回结果:
{"ticket":"gQH47joAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL2taZ2Z3TVRtNzJXV1Brb3ZhYmJJAAIEZ23sUwMEmm
3sUw==","expire_seconds":60,"url":"http:\/\/weixin.qq.com\/q\/kZgfwMTm72WWPkovabbI"}
参数 |
说明 |
ticket |
获取的二维码ticket,凭借此ticket可以在有效时间内换取二维码。 |
expire_seconds |
该二维码有效时间,以秒为单位。 最大不超过2592000(即30天)。 |
url |
二维码图片解析后的地址,开发者可根据该地址自行生成需要的二维码图片 |
通过ticket换取二维码
获取二维码ticket后,开发者可用ticket换取二维码图片。请注意,本接口无须登录态即可调用。
请求说明
HTTP GET请求(请使用https协议)https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET提醒:TICKET记得进行UrlEncode
返回说明
ticket正确情况下,http 返回码是200,是一张图片,可以直接展示或者下载。
HTTP头(示例)如下:
Accept-Ranges:bytes
Cache-control:max-age=604800
Connection:keep-alive
Content-Length:28026
Content-Type:image/jpg
Date:Wed, 16 Oct 2013 06:37:10 GMT
Expires:Wed, 23 Oct 2013 14:37:10 +0800
Server:nginx/1.4.1
错误情况下(如ticket非法)返回HTTP错误码404
二、获取微信用户详细信息
用户信息的获取是微信开发中比较常用的一个功能了,以下所有的用户信息的获取与更新,都是基于微信的 openid
的,并且是已关注当前账号的,其它情况可能无法正常使用。
获取实例
use
EasyWeChat\
Foundation\
Application;
$app =
new Application($options);
$userService = $app->user;
|
API 列表
获取用户信息
$userService->get($openId);
$userService->batchGet($openIds);
|
获取单个:
$user = $userService->get($openId);
echo $user->nickname;
|
获取多个:
$users = $userService->batchGet([$openId1, $openId2, ...]);
|
获取用户列表
$userService->lists($nextOpenId =
null);
|
example:
$users = $userService->lists();
{
"total":
2,
"count":
2,
"data": {
"openid": [
"",
"OPENID1",
"OPENID2"
]
},
"next_openid":
"NEXT_OPENID"
}
$users->total;
|
修改用户备注
$userService->remark($openId, $remark);
|
example:
$userService->remark($openId,
"僵尸粉");
|
获取用户所属用户组ID
$userService->group($openId);
|
example:
$userGroupId = $userService->group($openId);
|
获取公众号的黑名单列表
$userService->blacklist($beginOpenId =
null);
|
example:
$blacklist = $userService->blacklist();
|
拉黑用户
$userService->batchBlock(
array $openidList);
|
example:
$userService->batchBlock([
'openid1',
'openid2',
'openid3',
'...']);
|
取消拉黑用户
$userService->batchUnblock(
array $openidList);
|
example:
$userService->batchUnblock([
'openid1',
'openid2',
'openid3',
'...']);
|
其它
三、微信事件处理
我们在入门小教程一节以服务端为例讲解了一个基本的消息的处理,这里就不再讲服务器验证的流程了,请直接参考前面的入门实例即可。
服务端的作用呢,在整个微信开发中主要是负责 接收用户发送过来的消息,还有 用户触发的一系列事件。
首先我们得厘清一下消息与事件的回复,当你收到用户消息后(消息由微信服务器推送到你的服务器),在你对消息进行一些处理后,不管是选择回复一个消息还是什么不都回给用户,你也应该给微信服务器一个 “答复”,如果是选择回复一条消息,就直接返回一个消息xml就好,如果选择不作任何回复,你也得回复一个空字符串或者字符串 SUCCESS
(不然用户就会看到 该公众号暂时无法提供服务
)。
基本使用
在 SDK 中呢,使用 setMessageHandler(callable $callback)
来设置消息处理函数:
use
EasyWeChat\
Foundation\
Application;
$app =
new Application($options);
$server = $app->server;
$server->setMessageHandler(
function ($message) {
return
"您好!欢迎关注我!";
});
$response = $server->serve();
$response->send();
|
这里我们使用 setMessageHandler
传入了一个 闭包(Closure),该闭包接收一个参数 $message
为消息对象(Collection),这里需要注意的时,与 2.0 不同,2.0 当中我们对消息与事件做了区分,还对消息进行了分类(按 MsgType)。在 3.0 后,所有的消息包括事件都会使用 setMessageHandler
来处理,也就是说你可能需要在里面进行一些判断,例如:
$server->setMessageHandler(
function ($message) {
switch ($message->MsgType) {
case
'event':
return
'收到事件消息';
break;
case
'text':
return
'收到文字消息';
break;
case
'image':
return
'收到图片消息';
break;
case
'voice':
return
'收到语音消息';
break;
case
'video':
return
'收到视频消息';
break;
case
'location':
return
'收到坐标消息';
break;
case
'link':
return
'收到链接消息';
break;
default:
return
'收到其它消息';
break;
}
});
|
当然,因为这里 setMessageHandler
接收一个 callable
的参数,所以你不一定要传入一个 Closure 闭包,你可以选择传入一个函数名,一个 [$class, $method]
或者 Foo::bar
这样的类型。
注意,默认没有验证是否为微信的请求,部署上线建议关掉 debug 模式。
某些情况,我们需要直接使用 $message
参数,那么怎么在 setMessageHandler
闭包外调用呢?
$message = $server->getMessage();
|
注意:$message
是一个数组类型的数据,使用的时候这样使用:$message['ToUserName']
请求消息的属性
当你接收到用户发来的消息时,可能会提取消息中的相关属性,那么请参考:
请求消息基本属性(以下所有消息都有的基本属性):
$message->ToUserName 接收方帐号(该公众号 ID)
$message->FromUserName 发送方帐号(OpenID, 代表用户的唯一标识)
$message->CreateTime 消息创建时间(时间戳)
$message->MsgId 消息 ID(64位整型)
文本:
$message->MsgType text
$message->Content 文本消息内容
图片:
$message->MsgType image
$message->PicUrl 图片链接
语音:
$message->MsgType voice
$message->MediaId 语音消息媒体id,可以调用多媒体文件下载接口拉取数据。
$message->Format 语音格式,如 amr,speex 等
$message->Recognition * 开通语音识别后才有
> 请注意,开通语音识别后,用户每次发送语音给公众号时,微信会在推送的语音消息XML数据包中,增加一个 `Recongnition` 字段
视频:
$message->MsgType video
$message->MediaId 视频消息媒体id,可以调用多媒体文件下载接口拉取数据。
$message->ThumbMediaId 视频消息缩略图的媒体id,可以调用多媒体文件下载接口拉取数据。
小视频:
$message->MsgType shortvideo
$message->MediaId 视频消息媒体id,可以调用多媒体文件下载接口拉取数据。
$message->ThumbMediaId 视频消息缩略图的媒体id,可以调用多媒体文件下载接口拉取数据。
事件:
$message->MsgType event
$message->Event 事件类型 (如:subscribe(订阅)、unsubscribe(取消订阅) ..., CLICK 等)
# 扫描带参数二维码事件
$message->EventKey 事件KEY值,比如:qrscene_123123,qrscene_为前缀,后面为二维码的参数值
$message->Ticket 二维码的 ticket,可用来换取二维码图片
# 上报地理位置事件
$message->Latitude 23.137466 地理位置纬度
$message->Longitude 113.352425 地理位置经度
$message->Precision 119.385040 地理位置精度
# 自定义菜单事件
$message->EventKey 事件KEY值,与自定义菜单接口中KEY值对应,如:CUSTOM_KEY_001, www.qq.com
地理位置:
$message->MsgType location
$message->Location_X 地理位置纬度
$message->Location_Y 地理位置经度
$message->Scale 地图缩放大小
$message->Label 地理位置信息
链接:
$message->MsgType link
$message->Title 消息标题
$message->Description 消息描述
$message->Url 消息链接
回复消息
回复的消息可以为 null
,此时 SDK 会返回给微信一个 “SUCCESS”,你也可以回复一个普通字符串,比如:欢迎关注 overtrue.
,此时 SDK 会对它进行一个封装,产生一个 EasyWeChat\Message\Text
类型的消息并在最后的 $server->serve();
时生成对应的消息 XML 格式。
如果你想返回一个自己手动拼的原生 XML 格式消息,请返回一个 EasyWeChat\Message\Raw
实例即可。