4.2.2　封装事件

当用户对公众账号做出某种操作后，微信服务器会将相应的事件消息以XML格式通过POST方式发送到我们填写的URL（公众账号服务器的入口）上，开发者文档的“接收事件推送”中定义了每种事件的消息结构，如图4-6所示。

图4-6　接收事件推送

1.事件基类

每种事件都包含ToUserName、FromUserName、CreateTime、MsgType和Event5个参数，参数的描述如表4-6所示。

表4-6　所有事件共有的参数描述

事件基类的代码如下：

/**
 * 事件基类
 * 
 * @author liufeng
 * @date 2013-11-02
 */
public class BaseEvent {
  // 开发者微信号
  private String ToUserName;
  // 发送方账号（一个OpenID）
  private String FromUserName;
  // 消息创建时间 （整型）
  private long CreateTime;
  // 消息类型
  private String MsgType;
  // 事件类型
  private String Event;
 
  public String getToUserName() {
      return ToUserName;
  }
 
  public void setToUserName(String toUserName) {
      ToUserName = toUserName;
  }
 
  public String getFromUserName() {
      return FromUserName;
  }
 
  public void setFromUserName(String fromUserName) {
      FromUserName = fromUserName;
  }
 
  public long getCreateTime() {
      return CreateTime;
  }
 
  public void setCreateTime(long createTime) {
      CreateTime = createTime;
  }
 
  public String getMsgType() {
      return MsgType;
  }
 
  public void setMsgType(String msgType) {
      MsgType = msgType;
  }
 
  public String getEvent() {
      return Event;
  }
 
  public void setEvent(String event) {
      Event = event;
  }
}

2.关注/取消关注事件

当用户关注或取消关注公众账号时，微信服务器会向公众账号服务器推送如下格式的数据：

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[subscribe]]></Event>
</xml>

关注事件和取消关注事件的消息类型都是event。参数Event等于subscribe时，表示关注事件；Event等于unsubscribe时，表示取消关注事件。上面的消息结构对应的Java类如下：

/**
 * 关注/取消关注事件
 * 
 * @author liufeng
 * @date 2013-11-04
 */
 public class SubscribeEvent extends BaseEvent {
 
}

3.扫描带参数二维码事件

当用户扫描带场景值的二维码时，如果用户还未关注公众账号，关注后微信服务器会向公众账号服务器推送如下格式的数据：

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[subscribe]]></Event>
  <EventKey><![CDATA[qrscene_123123]]></EventKey>
  <Ticket><![CDATA[TICKET]]></Ticket>
</xml>

参数EventKey表示事件KEY值，qrscene_为固定前缀，后面为二维码的参数值；参数Ticket可用于换取二维码图片。

当用户扫描带场景值的二维码时，如果用户已经关注公众账号，微信服务器会向公众账号服务器推送一条事件类型为scan的消息，格式如下：

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[scan]]></Event>
  <EventKey><![CDATA[SCENE_VALUE]]></EventKey>
  <Ticket><![CDATA[TICKET]]></Ticket>
</xml>

可以看出，扫描带参数二维码事件的两种消息结构完全相同，不同的只是事件类型和事件KEY值，该事件的消息结构对应的Java类代码如下：

/**
 * 扫描带参数二维码事件
 * 
 * @author liufeng
 * @date 2013-11-04
 */
public class QRCodeEvent extends BaseEvent {
  // 事件KEY值
  private String EventKey;
  // 用于换取二维码图片
  private String Ticket;
 
  public String getEventKey() {
      return EventKey;
  }
 
  public void setEventKey(String eventKey) {
      EventKey = eventKey;
  }
 
  public String getTicket() {
      return Ticket;
  }
 
  public void setTicket(String ticket) {
      Ticket = ticket;
  }
}

4.上报地理位置事件

服务号通过微信认证后就能使用高级接口，高级接口中的“获取用户地理位置”默认是关闭状态，开启后，用户关注并进入公众账号时，会弹出提示框让用户确认是否允许公众账号使用其地理位置，如图4-7所示。

图4-7　提示是否允许使用地理位置

如图4-7所示的弹出框只在关注后出现一次，用户以后可以在公众账号的详细资料界面进行设置。用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理位置，或在进入会话后每5秒上报一次地理位置。公众账号服务器将会收到一条事件类型为LOCATION的消息，消息结构如下：

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[LOCATION]]></Event>
  <Latitude>23.137466</Latitude>
  <Longitude>113.352425</Longitude>
  <Precision>119.385040</Precision>
</xml>

该消息中的主要参数描述如表4-7所示。

表4-7　上报地理位置事件的主要参数描述

上报地理位置事件的消息结构对应的Java类如下：

/**
 * 上报地理位置事件
 * 
 * @author liufeng
 * @date 2013-11-02
 */
public class LocationEvent extends BaseEvent {
  // 地理位置纬度
  private String Latitude;
  // 地理位置经度
  private String Longitude;
  // 地理位置精度
  private String Precision;
 
  public String getLatitude() {
      return Latitude;
  }
 
  public void setLatitude(String latitude) {
      Latitude = latitude;
  }
 
  public String getLongitude() {
      return Longitude;
  }
 
  public void setLongitude(String longitude) {
      Longitude = longitude;
  }
 
  public String getPrecision() {
      return Precision;
  }
 
  public void setPrecision(String precision) {
      Precision = precision;
  }
}

5.自定义菜单事件

当用户点击click类型的菜单按钮时，微信服务器会向公众账号服务器推送一条事件类型为CLICK的消息，消息结构如下：

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[CLICK]]></Event>
  <EventKey><![CDATA[EVENTKEY]]></EventKey>
</xml>

这里的EventKey与自定义菜单接口中的KEY值相对应，通过它来识别用户点击的是哪个菜单按钮。自定义菜单事件的消息结构对应的Java类代码如下：

/**
 * 自定义菜单事件
 * 
 * @author liufeng
 * @date 2013-11-04
 */
public class MenuEvent extends BaseEvent {
  // 事件KEY值，与自定义菜单接口中KEY值对应
  private String EventKey;
 
  public String getEventKey() {
      return EventKey;
  }
 
  public void setEventKey(String eventKey) {
      EventKey = eventKey;
  }
}

注意点击view类型（跳转到URL）的菜单按钮时，微信服务器不会推送自定义菜单事件。