View Source WeChat (elixir_wechat v0.4.6)
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"):
- The
WeChat.Storage.Client
storage adapter behaviour is required for thecommon
application; - The
WeChat.Storage.ComponentClient
storage adapter behaviour is required for thecomponent
application.
Use this library in the hub web app:
- The
WeChat.Storage.Hub
storage adapter behaviour is required for thecommon
application; - The
WeChat.Storage.ComponentHub
storage adapter behaviour is required for thecomponent
application.
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
implementsWeChat.Storage.Client
behaviour, and is used for thecommon
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
implementsWeChat.Storage.ComponentClient
behaviour, and is used for thecomponent
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
Usage
as-common-application
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
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
@type error() :: atom() | WeChat.Error.t()
@type method() :: :head | :get | :delete | :trace | :options | :post | :put | :patch
Link to this section Functions
@spec 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.
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.
@spec 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
Options
:appid
, required, if you use a global module to assemble it, this value is optional. If you are using acommon
application,appid
means the application id of your WeChat Official Account; if you are acomponent
application,appid
means the application id of your WeChat Official Account third-party platform application.:authorizer_appid
, optional, if you are using acomponent
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 foraccess_token
,jsapi_ticket
, andcard_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 properaccess_token
into the query of each request, so we do NOT need to inputaccess_token
parameter.:opts
, optional, custom, per-request middleware or adapter options (exported fromTesla
)
@spec 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.
@spec sign_card(wxcard_ticket :: String.t(), card_id :: String.t()) :: WeChat.CardSignature.t()
See WeChat.sign_card/1
.
@spec sign_card( wxcard_ticket :: String.t(), card_id :: String.t(), openid :: String.t() ) :: WeChat.CardSignature.t()
See WeChat.sign_card/1
.
@spec 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.