WeChat (elixir_wechat v0.4.5) View Source

The link to WeChat Official Account Platform API document in Chinese | English.

Currently, there are two ways to use the WeChat's APIs:

  • As common application, directly integrates WeChat's APIs after turn on your WeChat Official Account into the developer mode (see details);
  • As component application, authorizes your WeChat Official Account to the WeChat Official Account third-party platform application, leverages a set of common solutions from the third-party platform (see details).

Refer the official document's recommend to manage access token (see details), we need to temporarily storage access token in a centralization way, we prepare four behaviours to manage the minimum responsibilities for each use case.

Use this library in the 3rd-party web app which can read the temporary storage data (e.g. access token/jsapi-ticket/card-ticket) from the centralization nodes(hereinafter "hub"):

Use this library in the hub web app:

As usual, the hub web app is one-off setup to use this library, most of time we use elixir_wechat is in the 3rd-party web app as a client, so here provide a default storage adapter to conveniently initialize it as a client use case:

  • The WeChat.Storage.Adapter.DefaultClient implements WeChat.Storage.Client behaviour, and is used for the common application by default:

    defmodule MyClient do
      use WeChat,
        adapter_storage: {:default, "http://localhost:4000"}
    end
    #
    # the above equals the following
    #
    defmodule MyClient do
      use WeChat,
        adapter_storage: {WeChat.Storage.Adapter.DefaultClient, "http://localhost:4000"}
    end
  • The WeChat.Storage.Adapter.DefaultComponentClient implements WeChat.Storage.ComponentClient behaviour, and is used for the component application by default:

    defmodule MyComponentClient do
      use WeChat.Component,
        adapter_storage: {:default, "http://localhost:4000"}
    end
    #
    # the above equals the following
    #
    defmodule MyComponentClient do
      use WeChat.Component,
        adapter_storage: {WeChat.Storage.Adapter.DefaultComponentClient, "http://localhost:4000"}
    end

Usage

As common application

defmodule MyClient do
  use WeChat,
    adapter_storage: {:default, "http://localhost:4000"},
    appid: "MyAppID"
end

MyClient.request(:post, url: "WeChatURL1", body: %{}, query: [])
MyClient.request(:get, url: "WeChatURL2", query: [])

Or use WeChat.request/2 directly

WeChat.request(:post, url: "WeChatURL1",
  appid: "MyAppID", adapter_storage: {:default, "http://localhost:4000"},
  body: %{}, query: [])

WeChat.request(:get, url: "WeChatURL2",
  appid: "MyAppID", adapter_storage: {:default, "http://localhost:4000"},
  query: [])

As component application

defmodule MyComponentClient do
  use WeChat.Component,
    adapter_storage: {:default, "http://localhost:4000"},
    appid: "MyAppID",
    authorizer_appid: "MyAuthorizerAppID"
end

MyComponentClient.request(:post, url: "WeChatURL1", body: %{}, query: [])
MyComponentClient.request(:post, url: "WeChatURL2", query: [])

Or use WeChat.request/2 directly

WeChat.request(:post, url: "WeChatURL1",
  appid: "MyAppID", authorizer_appid: "MyAuthorizerAppID",
  adapter_storage: {:default, "http://localhost:4000"}, body: %{}, query: [])

WeChat.request(:get, url: "WeChatURL2",
  appid: "MyAppID", authorizer_appid: "MyAuthorizerAppID",
  adapter_storage: {:default, "http://localhost:4000"}, query: [])

Link to this section Summary

Functions

The expire time (in seconds) to access_token and ticket temporary storage, by default it is 7200 seconds.

A function helper to fetch common application's access token.

Call WeChat's HTTP API functions in a explicit way.

To initialize WeChat Card functions in JSSDK, use wxcard_ticket and card_id to generate a signature for this scenario, see official document.

To configure and load WeChat JSSDK in the target page's url properly, use jsapi_ticket and url to generate a signature for this scenario.

Link to this section Types

Specs

error() :: atom() | WeChat.Error.t()

Specs

method() :: :head | :get | :delete | :trace | :options | :post | :put | :patch

Link to this section Functions

Specs

expires_in() :: integer()

The expire time (in seconds) to access_token and ticket temporary storage, by default it is 7200 seconds.

For hub scenario, both common and component application can override this function in the defined basic module if needed, and then can use this function as a global setting to use in access_token and ticket life cycle management, for example:

defmodule MyHubComponentClient do
  use WeChat.Component,
    scenario: :hub,
    adapter_storage: MyComponentLocalStorage

  def expires_in(), do: 7000
end
defmodule MyHubCommonClient do
  use WeChat,
    scenario: :hub,
    adapter_storage: MyCommonLocalStorage

  def expires_in(), do: 7000
end

For client scenario, no need to use this function, the local registry for access_token and ticket will use hub's response(contain time related) when fetch/refresh access_token and ticket to manage them as a client side temporary cache.

Link to this function

fetch_access_token(appid, adapter_storage)

View Source

A function helper to fetch common application's access token.

When apply it to hub, if no available access token from hub's storage, there will use the set account's secret_key to refresh a new one.

Link to this function

request(method, options)

View Source

Specs

request(method :: method(), options :: Keyword.t()) ::
  {:ok, term()} | {:error, WeChat.Error.t()}

Call WeChat's HTTP API functions in a explicit way.

We can defined a global module to assemble appid, authorizer_appid(only used for "component" application), and adapter_storage.

For example:

defmodule MyClient do
  use WeChat,
    appid: "...",
    adapter_storage: "..."
end
defmodule MyComponentClient do
  use WeChat.Component,
    appid: "...",
    authorizer_appid: "...",
    adapter_storage: "..."
end

And then we can use MyClient or MyComponentClient to call request/2, as usual, there dose NOT need to pass the above parameters when invoke, but if needed you input them to override.

We can directly use WeChat.request/2 as well, in this way, the appid, authorizer_appid(only used for "component" application), and adapter_storage are required for each invoke.

The method parameter can be used as one of method/0.

Options

  • :appid, required, if you use a global module to assemble it, this value is optional. If you are using a common application, appid means the application id of your WeChat Official Account; if you are a component application, appid means the application id of your WeChat Official Account third-party platform application.
  • :authorizer_appid, optional, if you are using a component application, this value is required, the application id of your WeChat Official Account third-party platform application.
  • :adapter_storage, required, the predefined storage way to used for access_token, jsapi_ticket, and card_ticket, here provide a {:default, "MyHubURL"} as option.
  • :url, required, the URL to call WeChat's HTTP API function, for example, "/cgi-bin/material/get_materialcount", also you can input a completed URL like this "https://api.weixin.qq.com/cgi-bin/material/get_materialcount".
  • :host, optional, the host of URI to call WeChat's HTTP API function, if you input a completed URL with host, this value is optional, by default it is "api.weixin.qq.com".
  • :scheme, optional, the scheme of URI to call WeChat's HTTP API function, if you input a completed URL with scheme, this value is optional, by default it is "https".
  • :port, optional, the port of URI to call WeChat's HTTP API function, if you input a completed URL with port, this value is optional, by default it is "443"(as integer).
  • :body, optional, a map, decided by your used WeChat's HTTP API functions, following WeChat official document to setup the body of the request.
  • :query, optional, a keyword, decided by your used WeChat's HTTP API functions, following WeChat official document to setup the query string of the request, this library will automatically appended a proper access_token into the query of each request, so we do NOT need to input access_token parameter.
  • :opts, optional, custom, per-request middleware or adapter options (exported from Tesla)

Specs

sign_card(list :: [String.t()]) :: WeChat.CardSignature.t()

To initialize WeChat Card functions in JSSDK, use wxcard_ticket and card_id to generate a signature for this scenario, see official document.

Link to this function

sign_card(wxcard_ticket, card_id)

View Source

Specs

sign_card(wxcard_ticket :: String.t(), card_id :: String.t()) ::
  WeChat.CardSignature.t()

See WeChat.sign_card/1.

Link to this function

sign_card(wxcard_ticket, card_id, openid)

View Source

Specs

sign_card(
  wxcard_ticket :: String.t(),
  card_id :: String.t(),
  openid :: String.t()
) :: WeChat.CardSignature.t()

See WeChat.sign_card/1.

Link to this function

sign_jssdk(jsapi_ticket, url)

View Source

Specs

sign_jssdk(jsapi_ticket :: String.t(), url :: String.t()) ::
  WeChat.JSSDKSignature.t()

To configure and load WeChat JSSDK in the target page's url properly, use jsapi_ticket and url to generate a signature for this scenario.