Getting Started

安装

在你的 Gemfile加入：

gem 'weixin_authorize'

或者

gem 'weixin_authorize', git: "https://github.com/lanrion/weixin_authorize.git"

然后:

bundle

基本使用

• 初始化 WeixinAuthorize::Client 的实例，传入公众账号的app_id跟app_secret即可。

# 创建一个实例
$client ||= WeixinAuthorize::Client.new(ENV["APPID"], ENV["APPSECRET"])

• 为了避免用户填写app_id和app_secret出错，请务必在保存或者更新操作时，对其做验证。

$client.is_valid? # return true or false

高级API调用

获取用户管理信息

• 获取用户基本信息

  user_info = $client.user(ENV["OPENID"])

• 获取关注者列表

  followers = $client.followers

分组管理接口

• 创建分组:

  group = $client.create_group("test")

• 查询所有分组:

  groups = $client.groups

• 查询用户所在分组:

  group = $client.get_group_for(ENV["OPENID"])

• 修改分组名:

  group = $client.update_group_name(ENV["OPENID"], "new_group_name")

• 移动用户分组:

  group = $client.update_group_for_openid(ENV["OPENID"], "to_groupid")

自定义菜单

• 自定义菜单创建接口

  response = $client.create_menu(menu) # Hash or Json

• 自定义菜单查询接口

  response = $client.menu

• 自定义菜单删除接口

  response = $client.delete_menu

发送客服信息

• 发送文本信息:

  $client.send_text_custom(to_user, content)

• 发送图片信息:

  $client.send_image_custom(to_user, media_id)

• 发送语音消息:

  $client.send_voice_custom(to_user, media_id)

• 发送视频消息:

  $client.send_video_custom(to_user, media_id, options)

• 发送音乐消息:

  $client.send_music_custom(to_user, media_id, musicurl, hqmusicurl, options)

• 发送图文消息:

  $client.send_news_custom(to_user, articles=[])

生成带参数的二维码

• 创建临时二维码

  $client.create_qr_scene("123")

• 创建永久二维码

  $client.create_qr_limit_scene("1234")

• 通过ticket换取二维码, 直接访问返回的链接即可显示！

$client.qr_code_url("ticket_example_value")

上传下载多媒体文件

• 上传多媒体文件

$client.upload_media(image_file_or_path, "input_media_type")

目前Master分支, 支持任何格式与任何URL形式的图片上传. 你可以指定本地图片或者远程图片, 也可以使用不同格式的比如png, ico 等格式, 或者直接自己 File.new 出来的图片.

另外,语音与其他类型的媒体文件,没有测试过. :)

• 下载多媒体文件

注意：媒体文件在后台保存时间为3天，即3天后media_id失效。

$client.download_media_url(media_id)

返回一个Media远程下载链接，注意：包含access_token值，请务必在action层做好安全性，下载请第三方开发者自行根据Paperclip或者Carrierwave来保存。

多个公众账号情况下强烈建议使用 Redis来保存access_token

• 在微信官网中，http://mp.weixin.qq.com/wiki/index.php?title=获取access_token

access_token是公众号的全局唯一票据，公众号调用各接口时都需使用access_token。正常情况下access_token有效期为7200秒，重复获取将导致上次获取的access_token失效。由于获取access_token的api调用次数非常有限，建议开发者全局存储与更新access_token，频繁刷新access_token会导致api调用受限，影响自身业务。

• 原因：为了避免 多公众账号情况下 请求次数过多以及在请求中浪费不必要的资源（重新发起http请求获取），我们使用Redis 的Hash 结构，并使用appid加密后作为key来存储access_token，默认的生命周期为7200-10=6180 秒，详见：https://github.com/lanrion/weixin_authorize/blob/master/lib/weixin_authorize/client.rb#L71

• 添加 redis-namespace 到你的 Gemfile：

# Adds a Redis::Namespace class which can be used to namespace calls to Redis. This is useful when using a single instance of Redis with multiple, different applications.
# http://github.com/resque/redis-namespace
gem "redis-namespace", "~> 1.4.1"

• 添加被始化文件：config/initializers/weixin_authorize.rb

# 这里修改成你的的命名空间。
namespace = "app_name_weixin:weixin_authorize"
redis = Redis.new(:host => "127.0.0.1", :port => "6379", :db => 15)

# 每次重启时，会把当前的命令空间所有的access_token 清除掉。
exist_keys = redis.keys("#{namespace}:*")
exist_keys.each{|key|redis.del(key)}

# Give a special namespace as prefix for Redis key, when your have more than one project used weixin_authorize, this config will make them work fine.
redis = Redis::Namespace.new("#{namespace}", :redis => redis)

WeixinAuthorize.configure do |config|
  config.redis = redis
end

注意，如果不做上述的redis配置，则不会使用Redis来存放access_token，直接存在当前实例中

• 另外一个可选项是，你可以指定存储access_token的key值，多个公众账号，建议最好用id值即可（插件会进行加密转换），保持唯一性。

没有特别的需求，不建议使用。

$client ||= WeixinAuthorize::Client.new(ENV["APPID"], ENV["APPSECRET"], "your_store_key")

特别注意事项

access_token 每次请求后，上一次的access_token会失效。所以如果存储在Redis中，但同时又在另一边重新跑了一次请求access_token的操作，那么保存在Redis的access_token会失效，在开发环境下，restart你的Rails Server即可，清除所有access_token的代码如下：

# 每次重启时，会把当前的命令空间所有的access_token 清除掉。
exist_keys = redis.keys("#{namespace}:*")
exist_keys.each{|key|redis.del(key)}

所以 强烈建议在微信的沙盒测试环境下进行开发并测试 : 微信沙盒测试平台地址： http://mp.weixin.qq.com/debug/cgi-bin/sandboxinfo?action=showinfo&t=sandbox/index 一个微信号对应一个测试账号，申请后，app_id和app_secret_key, 一年内不会发生改变。