WeChat (elixir_wechat v0.2.2) 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"):
- 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
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
Fetch common access token, when apply it to hub, there will use your account's secret key
to refresh another 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
Fetch common access token, when apply it to hub, there will use your account's secret key
to refresh another access token.
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 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
)
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.
Specs
sign_card(wxcard_ticket :: String.t(), card_id :: String.t()) :: WeChat.CardSignature.t()
See WeChat.sign_card/1
.
Specs
sign_card( wxcard_ticket :: String.t(), card_id :: String.t(), openid :: String.t() ) :: WeChat.CardSignature.t()
See WeChat.sign_card/1
.
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.