- General Description
- Settings
- Multisite
- WeChat SDK
- Functions
- Hooks - actions & filters
- Templates
- JavaScript
WP Weixin provides integration between WordPress and WeChat. Register or authenticate users automatically in WeChat browser, use WeChat to create an account or authenticate on computers by scanning a QR code with WeChat, share posts in WeChat Moments and conversations or extend the plugin for more features!
- Woo WeChatPay: a payment gateway for WooCommerce.
- WP Weixin Pay: an extension to enable money transfers to an Official Account.
Developers are encouraged to build plugins and themes integrated with WeChat with WP Weixin as a core, leveraging its publicly available functions, actions and filters, or directly make use of the provided SDK.
If you wish to see your plugin added to this list, please contact the author.
- Requires a China Mainland WeChat Official Account (Subscription or Service - Service is required if used with companion plugins dealing with payments).
- A domain used by WordPress must be registered in an Official Account's backend
- The plugin itself does not require programming knowledge, and provides really useful functionalities out of the box. Where it really shines though is when used by developers to extend its functionalities (mainly through the pre-initialised JS SDK, the WeChat Responder, and various provided functions, actions and filters).
To register a domain and authorize communication between it and the WeChat APIs (frontend JS and server side), the domain must be linked with an ICP license first. Then, on https://mp.weixin.qq.com:
- connect to the Official Account's backend
- click the "Interface Privilege" menu item
- in the list, search for "Web Page Authorization" and click the "Modify" link
- add the domain in both "JS interface security domain name" and "Webpage authorization domain name" by clicking the "Set-up" link for both sections (without the protocol
http
orhttps
) - making sure to include theMP_verify_[some_code].txt
files to the root of the website corresponding to the domain registered as instructed, accessible publicly.
This plugin adds the following major features to WordPress:
- WP Weixin settings page: configure the plugin with an Official Account (or as many as you want in multisite) in English or Chinese out of the box, with instructions for each option.
- WeChat Authentication: automatically create and authenticate users in WordPress in the WeChat browser, or allow users to scan a QR code with WeChat when using classic browsers (social login).
- WeChat Account Binding: let users bind/unbind their existing WordPress account with their WeChat account. Integrated with WooCommerce and Ultimate Member account pages, and may be integrated with any membership/account/profile plugin easily.
- WeChat Share: Share posts and pages on Moments or Send to chat, in a pretty way. Triggers JavaScript events for developers on success and failure.
- Force WeChat mobile: to prevent users from browsing the website outside of the WeChat browser. If accessed with a classic browser, the page displays a QR code.
- Force following the Official Account: to harvest WeChat followers, forcing users to follow the Official Account before accessing the content.
- WordPress Users screen override: to display WeChat names and WeChat avatars if they exist, instead of the default values in the user screen.
- WP Weixin QR code generator: to create custom codes.
- Menu integration: allows to set the Official Account menus in WordPress when the WeChat Responder is enabled.
- Welcome message: sends a welcome message in WeChat when a user follows the Official Account ; allows to do so with WordPress when the WeChat Responder is enabled.
- Developers - WeChat Responder: for developers to receive and respond to calls made by WeChat's API.
- Developers - WeChat JS_SDK: the
wx
JavaScript global variable is pre-configured with a signed package to leverage the JavaScript SDK of WeChat in WordPress themes more easily.
Compatible with WooCommerce, WooCommerce Multilingual, WPML, Ultimate Member, WordPress Multisite, and many caching plugins.
This plugin uses WordPress WP_Object_Cache
to optimise the number of database queries, ensuring only the proper amount is fired on each page load. Because the WP_Object_Cache
object can be affected by third-party plugins, it is required that such plugins implement the wp_cache_add_non_persistent_groups
function to avoid side effects.
See below examples of popular cache plugins compatible with WP Weixin:
The following settings are available on the WP Weixin settings page.
Required settings below are the minimal configuration necessary for the plugin to have any effect.
Name | Required | Type | Description |
---|---|---|---|
Enable | Yes | checkbox | Enable WP Weixin - requires a valid configuration. |
WeChat App ID | Yes | text | The AppId in the backend at https://mp.weixin.qq.com/ under Development > Basic configuration. |
WeChat App Secret | Yes | text | The AppSecret in the backend at https://mp.weixin.qq.com/ under Development > Basic configuration. |
WeChat OA Name | No | text | The name of the Official Account (recommended to enter the actual name). |
WeChat OA Logo URL | No | text | A URL to the logo of the Official Account - (recommended enter the URL of a picture of the actual logo). |
Enable WeChat authentication | No | checkbox | If enabled, users will be authenticated with their WeChat account in WordPress when visiting the site with the WeChat browser(if not, a session cookie with key 'wx_openId-' . apply_filters( 'wp_weixin_ms_auth_blog_id', 1 ) is set). |
Force WeChat mobile | No | checkbox | Make the website accessible only through the WeChat browser. If accessed with another browser, the page displays a QR code. |
Force follow (any page) | No | checkbox | Require the user to follow the Official Account before accessing the site with the WeChat browser. |
These settings are hidden by default and only available when:
- WordPress Multisite is installed
- The current user has the
manage_network_options
capability
They affect the entire multisite network.
Name | Type | Description |
---|---|---|
Force a blog for authentication | select | Replaced by an info text if a callback is hooked to wp_weixin_ms_auth_blog_id. Blog to use as proxy when authenticating users. |
Force a blog for WeChat payments | select | Replaced by an info text if a callback is hooked to wp_weixin_ms_pay_blog_id. Remains hidden if "Use merchant platform" option is not checked (needs WeChat payment integrated in a companion plugin). Blog to use as proxy when processing payments. If default, the JSAPI Payment Authorization URLs must be entered for all the blogs of the network doing payments, and the QR Payment callback URL must be capable of handling all the notifications coming from WeChat Pay API. |
Name | Type | Description |
---|---|---|
Use WeChat Responder | checkbox | Allow the website to receive messages from WeChat and respond to them. Server configuration must be enabled and configured in https://mp.weixin.qq.com/ under Development > Basic configuration. Required if using "Force follow" option in the Main Settings or WeChat Pay settings. |
WeChat Token | text | The Token in the backend at https://mp.weixin.qq.com/ under Development > Basic configuration. |
Encode messages | checkbox | Encode the communication between the website and the WeChat API (recommended). |
WeChat AES Key | text | The EncodingAESKey in the backend at https://mp.weixin.qq.com/ underDevelopment > Basic configuration. |
Send welcome message | checkbox | Send a welcome message when a user follows the Official Account. The following filters can be used to change the default values of the message: |
Welcome message image URL | text | A URL to the image used for the welcome message sent after a user follows the Official Account (external or from the Media Library). Default image is in /wp-weixin/images/default-welcome.png . |
These settings are hidden by default and only available if a WeChat Pay integration plugin such as WP Weixin Pay or Woo WeChatPay is installed and activated (this behavior may be altered using the wp_weixin_show_settings_section filter).
Name | Type | Description |
---|---|---|
Use merchant platform | checkbox | Allow users to send money to the Service Account with WeChat - an account at https://pay.weixin.qq.com/ is necessary. This setting is not configurable (forced to checked and hidden) if Woo WeChatPay plugin is activated.ย |
WeChat Merchant App ID | text | The AppID in the backend at https://pay.weixin.qq.com/ - can be different from the WeChat App ID as the WeChat Pay account may be linked to a different AppID. Leave empty to use the WeChat App ID. |
WeChat Merchant ID | text | The Merchant ID in the backend at https://pay.weixin.qq.com/index.php/extend/pay_setting . |
PEM certificate prefix | text | The prefix of the certificate files downloaded from https://pay.weixin.qq.com/index.php/core/cert/api_cert .Certificate files default prefix is apiclient (for apiclient_cert.pem and apiclient_key.pem files).Required notably to handle refunds through WeChat Pay. |
PEM certificate files path | text | The absolute path to the containing folder of the certificate files downloaded from https://pay.weixin.qq.com/index.php/core/cert/api_cert on the current file system.Example: /home/user/wechat-certificates .Must have read permissions for the user running PHP, and located outside of the web root. Required notably to handle refunds through WeChat Pay. |
In addition to these settings, the plugin provides onscreen help for what values to input for the different URLs in the merchant account's API configuration screen.
Name | Type | Description |
---|---|---|
Use a proxy | checkbox | Enable proxy. |
Proxy Host | text | IP address or URI of the proxy host. |
Proxy Port | text | Port to use to connect to the proxy host. |
Depending on your server configuration, a proxy may be needed if WordPress is behind a firewall or within a company network.
Name | Type | Description |
---|---|---|
Show WeChat name and picture in Users list page | checkbox | Override the display of the WordPress account names and avatars. |
Show WeChat public info | checkbox | Show the WeChat public information on user profile pages. Integrates with WooCommece and Ultimate Member. |
Show WeChat Account binding link | checkbox | Show a link to bind or unbind a WordPress account with a WeChat account on user profile pages. Integrates with WooCommece and Ultimate Member. |
Show WeChat Account authentication link | checkbox | Show a link to authenticate via QR code using a WeChat account on the WordPress login form. |
Official Account menu language awareness | checkbox | Customise the menu of the Official Account depending on user's language. By default, the language of the menu corresponding to the website's default language is used. This setting is only available if WPML is activated. |
Use custom persistence for access_token | checkbox | Use a custom persistence method for the Official Account access_token and its expiry timestamp. Warning - requires the implementation of:The parameter $access_info is an array with the keys token and expiry .Add the hooks above in a plugins_loaded action with a priority of 5 or less.Useful to avoid a race condition if the access_token information needs to be shared between multiple platforms. When unchecked, access_token & expiry timestamp are stored in the WordPress options table in the database. |
WP Weixin supports multisite installs of WordPress, wether using domain/subdomains or subdirectories. WP Weixin needs to be configured with the same settings and enabled on all the blogs where authentication is needed for a given Official Account.
With WeChat mobile authentication enabled, users visiting one of the blogs are automatically registered to the network, and added to the visited blog with the blog's default user role. Users are also automatically added to other blogs of the network upon visit when already registered on one of the blogs. This behavior can be changed with the wp_weixin_ms_auto_add_to_blog filter, for example if some of the blogs should not accept pre-authenticated WeChat users.
When using a domain/subdomain-based network of blogs, the main blog's domain/subdomain is used for cross-domain authentication. The behavior can be changed with the setting "Force a blog for authentication" in the Multisite Settings section of the plugin's page.
WeChat Pay integrated plugins can also support domain/subdomain-based network installs of WordPress Multisite by leveraging the functions, actions and filters provided by WP Weixin. The blog used for payment can be forced with the "Force a blog for WeChat payments" in the Multisite Settings section of the plugin's page.
WP Weixin Pay and Woo WeChatPay are examples of plugins integrated with WeChat Pay, working no matter the type of Multisite installation (subdirectory or domain/subdomain).
Unlike some plugins (commercial, obfuscated, and with dubious security standards), WP Weixin does not and will not rely on a crossdomain script dumped at the root of WordPress, but prefers to leverage the WordPress actions and filters.
It is possible to use the plugin with multiple Official Accounts on the same network, as long as the developer leverages wp_weixin_ms_auth_blog_id and wp_weixin_ms_pay_blog_id filter hooks to account for the different possible scenarios (see a simple example plugin here).
One of the most poweful tools provided by WP Weixin is its PHP Wechat Software Development Kit. To get an instance of the WeChat SDK, developers can use the following snippet:
$wechat_sdk = wp_weixin_get_wechat();
The returned value is an instance of WP_Weixin_Wechat
, which is a wrapper class for Wechat_SDK
: it ensures all settings and tokens are valid and initialised. Developers are discouraged from using the Wechat_SDK
class directly.
All the public methods of Wechat_SDK
are callable through the WP_Weixin_Wechat
object and should be used only for advanced purposes. These are low level methods compared to the provided functions: the latter should be used where possible, and developers should only use the SDK if no function achieving the intended result exists.
For the public methods available, please refer to the source code of Wechat_SDK
directly.
Quick, non-optimised example of advanced use - do something with the list of followers' openIDs, with error handling:
$wechat = wp_weixin_get_wechat();
$next_openid = true;
$result = $wechat->users();
$error = $wechat->getError();
// Warning - will loop until WeChat stops providing results ; do not use in production
while ( false !== $next_openid && ! $error ) {
if ( is_array( $result ) ) {
$next_openid = ( ! empty( $result['next_openid'] ) ) ? $result['next_openid'] : false;
// Do something with the returned data
do_something( $result['data'] );
} else {
$next_openid = false;
}
if ( $next_openid ) {
$result = $wechat->users( $next_openid );
$error = $wechat->getError();
}
}
if ( $error ) {
// Handle the error with the array containing the error information
handle_error( $error );
}
The functions listed below are made publicly available by the plugin for theme and plugin developers. Although the plugin's main classes can theoretically be instanciated without side effect if the $hook_init
parameter is set to false
, it is recommended to use only the following functions as there is no guarantee future updates won't introduce changes of behaviors.
Functions index:
- wp_weixin_is_wechat
- wp_weixin_ajax_safe
- wp_weixin_get_user_by_openid
- wp_weixin_get_user_by_unionid
- wp_weixin_get_wechat
- wp_weixin_get_options
- wp_weixin_get_option
- wp_weixin_wpml_switch_lang
- wp_weixin_get_signed_package
- wp_weixin_get_user_wechat_info
- wp_weixin_get_user_wechat_openid
- wp_weixin_get_auth_link
- wp_weixin_get_bind_link
- wp_weixin_unbind
- wp_weixin_bind
wp_weixin_is_wechat();
Description
Wether the visitor is using the WeChat browser.
Return value
(bool) Wether the vistor is using the WeChat browser.
wp_weixin_ajax_safe();
Description
Call this function in a WordPress ajax action. Allow interactions with WeChat API during an ajax request.
wp_weixin_get_user_by_openid( string $openid );
Description
Get a WordPress user by WeChat openID.
Parameters
$openid
(string) A WeChat openID.
Return value
(mixed) A
WP_User
if a WordPress user bound with a corresponding WeChat openID exists,false
otherwise.
wp_weixin_get_user_by_unionid( string $unionid, int $blog_id = false );
Description
Get a WordPress user by WeChat unionID, or a collection of WordPress users if several matches exist (possible only in the case of Multisite with multiple Official Accounts).
Parameters
$unionid
(string) A WeChat unionID.
Return value
(mixed) A
WP_User
object if a WordPress user with a corresponding WeChat unionID exists, an array ofWP_User
objects if several matches exist,false
otherwise.
wp_weixin_get_wechat();
Description
Get an instance of WP_Weixin_Wechat
(wrapper object for Wechat_SDK
- see WeChat SDK).
Return value
(WP_Weixin_Wechat) An instance of the wrapper object for
Wechat_SDK
.
wp_weixin_get_options();
Description
Get all the options used to configure the plugin.
Return value
(array) An associative array with all the options used to configure the plugin.
wp_weixin_get_option( $key );
Description
Get a specific option value used to configure the plugin.
Parameters
$key
(string) The option key.
Return value
(mixed) A string, boolean, or integer if the option has a value,
null
otherwise.
wp_weixin_wpml_switch_lang( $force = true );
Description
If WPML is active and the current user's WeChat language is known, switch the language to the value provided by the user's WeChat account.
Uses SitePress::switch_lang( $code = null, $cookie_lang = false )
- it is up to the developer to get up to speed with WMPL code base and documentation.
Parameters
$force
(bool) If set to
true
, will always switch the language ; iffalse
, the language will be switched only if "Browser language redirect" is enabled in WPML - defaulttrue
.
Return value
(bool) Wether
SitePress::switch_lang( $code = null, $cookie_lang = false )
was called.
wp_weixin_get_signed_package();
Description
Get a WeChat signed package to use with the WeChat JSAPI.
Note: the JavaScript global variable wx
is already properly signed and initialised with the complete jsApiList
if the wp-weixin-main-script
is already enqueued.
See the "JavaScript" section of the documentation for more details.
Return value
(array) The signed package to pass to a script via
wp_localize_script( $handle, $object_name, $l10n )
.
wp_weixin_get_user_wechat_info( int $user_id = false, bool $output = false );
Description
Get a user's WeChat information. Gets the current user's if the user ID is omitted.
Parameters
$user_id
(int) The ID of the user - default
false
.
$output
(bool) Wheter to output the information (using the wp-weixin-public-info template) - default
false
.
Return value
(mixed) An array of WeChat information if exists,
false
otherwise.
wp_weixin_get_user_wechat_openid( int $user_id = false );
Description
Get a user's WeChat openID. Gets the current user's if the user ID is omitted.
Parameters
$user_id
(int) The ID of the user - default
false
.
Return value
(mixed) A WeChat openID if exists,
false
otherwise.
wp_weixin_get_auth_link( bool $output = false, string $target = '' );
Description
Get a link to the WeChat authentication page.
This function has no effect in the WeChat browser.
Parameters
$output
(bool) Wether to output the link.
$target
(string) The target of the link.
Return value
(mixed) If
$output
is set totrue
, the link's markup -false
otherwise.
wp_weixin_get_bind_link( bool $output = false, string $target = '_blank' );
Description
Get a link to the WeChat account binding page.
This function has no effect in the WeChat browser.
Parameters
$output
(bool) Wether to output the link.
$target
(string) The target of the link.
Return value
(mixed) If
$output
is set totrue
, the link's markup -false
otherwise.
wp_weixin_unbind( int $user_id, string $open_id = '' );
Description
Unbind a WordPress user account previously bound with WeChat, effectively deleting all the recorded information related to the associated WeChat account.
Note: a WeChat-only WordPress user account is a WordPress account that was created automatically by WP Weixin when opening the website in WeChat browser (Username following the wx-[openid]
pattern).
If a user_id
corresponding to a WeChat-only WordPress user account that may or may not have been previously bound is provided (Username following the wx-[openid]
or wx-bound-[openid]
pattern), the Username is updated with the wx-unbound-[openid]
pattern.
Parameters
$user_id
(int) The ID of the user.
$open_id
(string) The openID of the WeChat account - if left empty, set to the current user's recorded value.
Return value
(bool) Wether the account was unbound.
wp_weixin_bind( int $user_id, string $openid );
Description
Bind a WordPress user account with WeChat, effectively overwritting all the recorded information related to an associated WeChat account if exist.
Note: a WeChat-only WordPress user account is a WordPress account that was created automatically by WP Weixin when opening the website in WeChat browser (Username following the wx-[openid]
pattern).
A WeChat-only WordPress user account with the provided $openid
recorded must exist.
If a value for $user_id
corresponding to a WeChat-only WordPress user account that may or may not have been previously unbound is provided (Username following the wx-[openid]
or wx-unbound-[openid]
pattern), the Username is updated with the wx-bound-[openid]
pattern.
A given openID cannot be used to bind WeChat with multiple WordPress user accounts.
Parameters
$user_id
(int) The ID of the user.
$open_id
(string) The openID corresponding to a WeChat-only WordPress user account.
Return value
(bool) Wether the account was bound.
WP Weixin gives developers the possibilty to customise its behavior with a series of custom actions and filters.
Actions index:
- wp_weixin_extensions
- wp_weixin_responder
- wp_weixin_save_access_info
- wp_weixin_before_user_profile_wechat_info
- wp_weixin_after_user_profile_wechat_info
- wp_weixin_before_bind_account
- wp_weixin_after_bind_account
- wp_weixin_before_unbind_account
- wp_weixin_after_unbind_account
- wp_weixin_before_tabs_settings
- wp_weixin_before_main_tab_settings
- wp_weixin_before_main_settings_inner
- wp_weixin_after_main_settings_inner
- wp_weixin_after_main_tab_settings
- wp_weixin_before_qr_tab_settings
- wp_weixin_after_qr_tab_settings
- wp_weixin_after_tabs_settings
- wp_weixin_before_settings
- wp_weixin_before_main_settings
- wp_weixin_after_main_settings
- wp_weixin_before_qr_settings
- wp_weixin_before_qr_settings_inner
- wp_weixin_after_qr_settings_inner
- wp_weixin_after_qr_settings
- wp_weixin_after_settings
- wp_weixin_handle_payment_notification
- wp_weixin_endpoints
- wp_weixin_handle_auto_refund
- wp_weixin_pay_refund_failed
do_action( 'wp_weixin_extensions', mixed $wechat, mixed $wp_weixin_settings, mixed $wp_weixin, mixed $wp_weixin_auth, mixed $wp_weixin_responder, mixed $wp_weixin_menu );
Description
Fired when WP Weixin is fully loaded and if "Enabled" is checked in WP Weixin Main Settings. Typically used to build plugins using WP Weixin as a core.
Note: it is recommended to use the provided functions where possible instead of the methods of this action's parameters, as there is no guarantee future updates won't introduce changes of behaviors.
Parameters
$wechat
(mixed) A
WP_Weixin_Wechat
object.
$wp_weixin_settings
(mixed) A
WP_Weixin_Settings
object.
$wp_weixin
(mixed) A
WP_Weixin
object.
$wp_weixin_auth
(mixed) A
WP_Weixin_Auth
object.
$wp_weixin_responder
(mixed) A
WP_Weixin_Responder
object if the WeChat Responder is enabled,false
otherwise.
$wp_weixin_menu
(mixed) A
WP_Weixin_Menu
object if the WeChat Responder is enabled,false
otherwise.
do_action( 'wp_weixin_responder', array $request_data );
Description
Fired after receiving a request from WeChat.
Parameters
$request_data
(array) The data sent in the request from WeChat.
do_action( 'wp_weixin_save_access_info', array $access_info );
Description
Fired after renewing the Official Account access_token if custom persistence is used. Used to save the access information - particularly useful to avoid a race condition if the access_token needs to be shared between multiple platforms.
Parameters
$access_info
(array) The access information in an associative array. Keys are
token
andexpiry
.
do_action( 'wp_weixin_before_user_profile_wechat_info', mixed $wechat_info, mixed $user );
Description
Fired before displaying WeChat public info on the user profile.
Parameters
$wechat_info
(mixed) An array of WeChat public info to display on the user profile if they exist,
false
otherwise.
$user
(mixed) A
WP_User
object if the user exists,false
otherwise.
do_action( 'wp_weixin_after_user_profile_wechat_info', mixed $wechat_info, mixed $user );
Description
Fired after displaying WeChat public info on the user profile.
Parameters
$wechat_info
(mixed) An array of WeChat public info displayed on the user profile,
false
otherwise.
$user
(mixed) A
WP_User
object if the user exists,false
otherwise.
do_action( 'wp_weixin_before_bind_account', int $user_id, int $wechat_user_id, array $wechat_user_blog_ids, int $current_blog_id );
Description
Fired before binding a WordPress user account with WeChat.
Parameters
$user_id
(int) The user ID.
$wechat_user_id
(int) ID of a WeChat-only WordPress user account (Username following the
wx-[openid]
pattern).
$wechat_user_blog_ids
(array) List of blog IDs the WeChat-only WordPress user account belongs to.
$current_blog_id
(int) The blog ID of the current blog.
do_action( 'wp_weixin_after_bind_account', bool $bound, int $user_id, int $wechat_user_id, array $wechat_user_blog_ids, int $current_blog_id );
Description
Fired after binding a WordPress user account with WeChat.
Parameters
$bound
(bool) Wether the WordPress user account was successfully bound with WeChat.
$user_id
(int) The user ID.
$wechat_user_id
(int) ID of a WeChat-only WordPress user account (Username following the
wx-[openid]
pattern).
$wechat_user_blog_ids
(array) List of blog IDs the WeChat-only WordPress user account belongs to.
$current_blog_id
(int) The blog ID of the current blog.
do_action( 'wp_weixin_before_unbind_account', int $user_id, string $openid );
Description
Fire before unbinding a WordPress user account from WeChat.
Parameters
$user_id
(int) The user ID.
$openid
(string) The WeChat openID.
do_action( 'wp_weixin_after_unbind_account', bool $unbound, int $user_id, string $openid );
Description
Fire after unbinding a WordPress user account from WeChat.
Parameters
$unbound
(bool) Wether the WordPress user account was successfully unbound from WeChat.
$user_id
(int) The user ID.
$openid
(string) The WeChat openID.
do_action( 'wp_weixin_before_tabs_settings' );
Description Fired before outputting the tabs of the WP Weixin page.
do_action( 'wp_weixin_before_main_tab_settings' );
Description Fired before outputting the main settings tab of the WP Weixin page.
do_action( 'wp_weixin_before_main_settings_inner' );
Description Fired before outputting the main settings content on the WP Weixin page.
do_action( 'wp_weixin_after_main_settings_inner' );
Description Fired after outputting the main settings content on the WP Weixin page.
do_action( 'wp_weixin_after_main_tab_settings' );
Description Fired after outputting the main settings tab of the WP Weixin page.
do_action( 'wp_weixin_before_qr_tab_settings' );
Description Fired before outputting the QR code generator tab of the WP Weixin page.
do_action( 'wp_weixin_after_qr_tab_settings' );
Description Fired after outputting the QR code generator tab of the WP Weixin page.
do_action( 'wp_weixin_after_tabs_settings' );
Description Fired after outputting the tabs of the WP Weixin page.
do_action( 'wp_weixin_before_settings' );
Description Fired before outputting the settings on the WP Weixin page.
do_action( 'wp_weixin_before_main_settings' );
Description Fired before outputting the main settings box on the WP Weixin page.
do_action( 'wp_weixin_after_main_settings' );
Description Fired after outputting the main settings box on the WP Weixin page.
do_action( 'wp_weixin_before_qr_settings' );
Description Fired before outputting the QR code generator on the WP Weixin page.
do_action( 'wp_weixin_before_qr_settings_inner' );
Description Fired before outputting the QR code generator box on the WP Weixin page.
do_action( 'wp_weixin_after_qr_settings_inner' );
Description Fired after outputting the QR code generator box on the WP Weixin page.
do_action( 'wp_weixin_after_qr_settings' );
Description Fired after outputting the QR code generator on the WP Weixin page.
do_action( 'wp_weixin_after_settings' );
Description Fired after outputting the settings on the WP Weixin page.
do_action( 'wp_weixin_endpoints' );
Description
Fired when adding WP Weixin rewrite rules. Useful for companion plugins to add their own, and make sure they are registered properly (rules are flushed when WP Weixin settings are saved).
do_action( 'wp_weixin_handle_payment_notification' );
Description
Fired when handling a WeChat Pay transaction notification.
Fired last by WP Weixin (PHP_INT_MIN
) ; should be fired earlier by companion plugins integrating with WeChat Pay.
See a WeChat Pay integration plugin skeleton for how to handle WeChat Pay notifications.
do_action( 'wp_weixin_handle_auto_refund', mixed $refund_result, array $payment_result );
Description
Fired after an automatic refund for a failed transaction has been attempted.
See a WeChat Pay integration plugin skeleton for how to handle WP Weixin automatic refund results.
Parameters
$refund_result
(mixed) An array containing the WeChat Pay API's response in case the refund wass successful,
false
otherwise.
$payment_result
(array) A payment notification result. Structure of a result:
array(
'success' => false, // optional - (bool) wether the transaction to handle was found ; default false
'data' => $data, // required - (array) return value of WP_Weixin_Wechat::getNotify()
'refund' => false, // optional - (mixed) false if no refund needed, true or an refund message for the user otherwise ; default false
'notify_error' => false, // optional - (mixed) false if no error, true or an error message otherwise ; if truthy and pay_handler set to true, WeChat Pay API will continue to send notifications for the transaction ; default false
'blog_id' => $blog_id, // required for multisite, optional otherwise - (int) the ID of the blog where the original transaction was made ; default the return value of get_current_blog_id()
'pay_handler' => false, // optional - (bool) wether the result is for the callback registered in the WeChat Pay backend ; default false
/* More custom items can safely be added to the array */
);
Filters index:
- wp_weixin_browser_page_qr_src
- wp_weixin_subscribe_src
- wp_weixin_follower_notice_title
- wp_weixin_follower_notice
- wp_weixin_auth_needed
- wp_weixin_debug
- wp_weixin_follower_welcome_title
- wp_weixin_follower_welcome_description
- wp_weixin_follower_welcome_url
- wp_weixin_follower_welcome_pic_url
- wp_weixin_get_access_info
- wp_weixin_jsapi_urls
- wp_weixin_pay_callback_url
- wp_weixin_settings
- wp_weixin_show_settings_section
- wp_weixin_show_setting
- wp_weixin_settings_fields
- wp_weixin_auth_redirect
- wp_weixin_scan_heartbeat_frequency
- wp_weixin_qr_cleanup_frequency
- wp_weixin_qr_lifetime
- wp_weixin_user_wechat_info
- wp_weixin_ms_auto_add_to_blog
- wp_weixin_ms_auth_blog_id
- wp_weixin_ms_pay_blog_id
- wp_weixin_locate_template_paths
- wp_weixin_get_user_by_openid
- wp_weixin_pay_notify_results
- wp_weixin_ecommerce_description
- wp_weixin_wechat_share_params
apply_filters( 'wp_weixin_browser_page_qr_src', string $src );
Description
Filter the source of the QR code to show on classic browsers for a page only accessible through WeChat browser.
Parameters
$src
(string) The source of the QR code to show on classic browsers.
apply_filters( 'wp_weixin_subscribe_src', string $src );
Description
Filter the source of the QR code used to follow the Official Account.
Parameters
$src
(string) The source of the QR code.
apply_filters( 'wp_weixin_follower_notice_title', string $title );
Description
Filter the title of the page displaying the QR code to follow the Official Account.
Parameters
$title
(string) The title of the page - default "Follow Us!".
apply_filters( 'wp_weixin_follower_notice', string $notice );
Description
Filter the message displayed on the page displaying the QR code to follow the Official Account.
Parameters
$notice
(string) The displayed message - default "Please scan this QR Code to follow us before accessing this content.".
apply_filters( 'wp_weixin_auth_needed', bool $needs_auth );
Description
Wether the URL needs the user to be authenticated using WeChat. When "Enable WeChat authentication" is checked in the settings, URLs triggering WordPress's init
action hook need authentication by default, unless they are whitelisted using this filter. By default, all the admin pages, the WP Weixin classic browser authentication page, the WordPress ajax endpoint, the WeChat responder endpoint, and the WooCommerce API endpoints are whitelisted and accessible outside WeChat.
Parameters
$needs_auth
(bool) Wether authentication is needed to visit the URL.
apply_filters( 'wp_weixin_debug', bool $debug );
Description
Filter wether to activate debug mode (PHP error logs, JavaScript console messages, JavaScript alerts).
Parameters
$debug
(bool) Wether debug mode is activated - default
WP_DEBUG
constant value.
apply_filters( 'wp_weixin_follower_welcome_title', string $title, mixed $before_subscription );
Description
Filter the title of the message the user receives when following the Official Account.
Parameters
$title
(string) The title - default "'Welcome
user_name
!'" whereuser_name
is the user's WeChat Name.
$before_subscription
(mixed) If numeric, the
WP_Post
ID of the last page the user was visiting ; if string, the URL of the last page the user was visiting - defaulthome_url()
.
apply_filters( 'wp_weixin_follower_welcome_description', string $description, mixed $before_subscription );
Description
Filter the description of the message the user receives when following the Official Account.
Parameters
$description
(string) The description - default "Thank you for subscribing our official account!".
$before_subscription
(mixed) If numeric, the
WP_Post
ID of the last page the user was visiting ; if string, the URL of the last page the user was visiting - defaulthome_url()
.
apply_filters( 'wp_weixin_follower_welcome_url', string $url, mixed $before_subscription );
Description
Filter the URL the user will be redirected to when interacting with the message received when following the Official Account.
Parameters
$url
(string) The URL the user will be redirected to - default
home_url()
if no URL was recorded before sending the templated message.
$before_subscription
(mixed) If numeric, the
WP_Post
ID of the last page the user was visiting ; if string, the URL of the last page the user was visiting - defaulthome_url()
.
apply_filters( 'wp_weixin_follower_welcome_pic_url', string $pic_url, mixed $before_subscription );
Description
Filter the URL of the picture displayed on the message the user receives when following the Official Account.
Parameters
$pic_url
(string) The URL of the picture - default
WP_PLUGIN_URL . '/wp-weixin/images/default-welcome.png'
.
$before_subscription
(mixed) If numeric, the
WP_Post
ID of the last page the user was visiting ; if string, the URL of the last page the user was visiting - defaulthome_url()
.
apply_filters( 'wp_weixin_get_access_info', array $access_info );
Description
Filter the access token and token expiry when requesting the WP_Weixin_WeChat
object (wrapper of a Wechat_SDK
object) if custom persistence is used - particularly useful to avoid a race condition if the access token needs to be shared between multiple platforms.
Parameters
$access_info
(array) The access information in an associative array. Value types and keys: (string)
token
, (int)expiry
.
apply_filters( 'wp_weixin_jsapi_urls', array $jsapi_urls );
Description
Filter the URLs necessary to register on the WeChat merchant account's API configuration screen - used when another plugin implements WeChat Pay integration.
Parameters
$jsapi_urls
(array) The URLs to register on the WeChat merchant account's API configuration screen.
apply_filters( 'wp_weixin_pay_callback_endpoint', string $endpoint );
Description
Filter the endpoint of the QR Payment URL necessary to register on the WeChat merchant account's API configuration screen - used when implementing WeChat Pay integration.
Parameters
$callback_url
(string) The endpoint of the QR Payment URL to register on the WeChat merchant account's API configuration screen (example:
/my_plugin/notify
).
apply_filter( 'wp_weixin_settings', $settings );
Description
Filter the settings used to configure the plugin.
Hooked functions or methods need to be added to this filter in a plugins_loaded
action hook of priority of 5
or less.
Parameters
$settings
(array) The settings used to configure the plugin.
apply_filters( 'wp_weixin_show_settings_section', bool $show_section, string $section_name, array $section );
Description
Filter wether to show a settings section on the WP Weixin settings page.
Parameters
$show_section
(bool) Wether to show the settings section on the WP Weixin settings page.
$section_name
(string) The name of the settings section.
$section
(array) The section's settings.
apply_filters( 'wp_weixin_show_setting', bool $show_setting, string $section_name, int $index, array $value );
Description
Filter wether to show a setting on the WP Weixin settings page.
Parameters
$show_setting
(bool) Wether to show the setting on the WP Weixin settings page.
$section_name
(string) The name of the section the setting belongs to.
$index
(int) The index of the setting in the section.
$value
(array) The setting.
apply_filters( 'wp_weixin_settings_fields', array $settings_fields );
Description
Filter the settings fields displayed on the WP Weixin settings page.
Parameters
$include_section
(array) The settings fields displayed on the WP Weixin settings page.
apply_filters( 'wp_weixin_auth_redirect', mixed $redirect, bool $auth, bool $has_error );
Description
Filter the URL to redirect to when QR code authentication in classic browsers is performed.
Parameters
$redirect
(mixed) The URL to redirect to when authentication is performed, or
false
if no redirect. Default ishome_url()
in case of successful authentication.
$auth
(bool) Wether the authentication was a performed -
true
if successful,false
if an error occurred.
$has_error
(bool) Wether an error occurred.
apply_filters( 'wp_weixin_scan_heartbeat_frequency', int $frequency );
Description
Filter the frequency of the checks when waiting for QR code scan confirmation in classic browsers.
Parameters
$frequency
(int) The frequency in milliseconds. Default
1000
.
apply_filters( 'wp_weixin_qr_cleanup_frequency', string $frequency );
Description
Filter the frequency to clean up expired QR code data.
Parameters
$frequency
(string) The frequency. Default
'hourly'
.
apply_filters( 'wp_weixin_qr_lifetime', int $lifetime );
Description
Filter the lifetime of a potentially sensitive QR code, such as WeChat authentication or WeChat account binding.
Parameters
$lifetime
(int) The lifetime in seconds. Default
600
.
apply_filters( 'wp_weixin_user_wechat_info', mixed $wechat_info, int $user_id );
Description
Filter the user WeChat information.
Parameters
$wechat_info
(mixed) An array of WeChat information if exist,
false
otherwise.
$lifetime
(int) The user ID - default
0
.
apply_filters( 'wp_weixin_ms_auto_add_to_blog', bool $auto_add_to_blog, int $blog_id, int $user_id );
Description
Filter wether to automatically add the user to the visited blog on the network when authenticated with WeChat.
Parameters
$auto_add_to_blog
(bool) Wether to automatically add the user to the visited blog on the network when authenticated with WeChat - default
true
.
$blog_id
(int) The ID of the visited blog.
$user_id
(int) The ID of the user visiting the blog.
apply_filters( 'wp_weixin_ms_auth_blog_id', int $auth_blog_id );
Description
Filter the blog ID used for authentication - by default, it is assumed the domain name of the default blog is registered in WeChat backend.
Warning: to make sure WP Weixin supports multiple Official Accounts, the openIDs of bound accounts are stored using a user meta record containing the value of $auth_blog_id
in its meta key ('wx_openid-' . $auth_blog_id
).
If WeChat-bound WordPress users already exist (manually bound or automatically created when visiting the site with the WeChat browser), applying this filter and return an altered value of $auth_blog_id
will break the relationship between the user and the recorded openID during runtime.
It is up to the developer to update the database directly, or run a one-time use code snippet like below.
Example of code snippet to run after changing the blog ID used for authentication in case WordPress users are already bound with WeChat:
global $wpdb;
$old_auth_blog_id = 1;
$new_auth_blog_id = 2;
$wpdb->query(
$wpdb->prepare(
"UPDATE $wpdb->usermeta SET `meta_key` = 'wx_openid-%d' WHERE `meta_key` = 'wx_openid-%d';",
$new_auth_blog_id,
$old_auth_blog_id
)
);
Parameters
$auth_blog_id
(int) The ID of the blog to use when doing WeChat authentication. Default
1
.
apply_filters( 'wp_weixin_ms_pay_blog_id', int $pay_blog_id );
Description
Filter the blog ID used to build the URLs allowed to call and receive payment notifications from the WeChat Pay API - by default, it is assumed the domain ( or subdomain ) corresponding to the ID of the the current blog is registered in WeChat backend. Useful in case several instances of WooCommerce are running on the same network, or in the case of a network connected to several Official Accounts.
Parameters
$pay_blog_id
(int) The ID of the blog used to build the QR Payment callback URL. Default
get_current_blog_id()
.
apply_filters( 'wp_weixin_locate_template_paths', array $paths, string $plugin_name );
Description
Filter the possible paths of templates included by WP Weixin and companion plugins.
Parameters
$paths
(array) The possible paths. Default (where
$template_name
is the template's file name):array( 'plugins/wp-weixin/' . $plugin_name . $template_name, 'wp-weixin/' . $plugin_name . $template_name, 'plugins/' . $plugin_name . $template_name, $plugin_name . $template_name, 'wp-weixin/' . $template_name, $template_name, );
$plugin_name
(string) The name of the plugin the template belongs to.
apply_filters( 'wp_weixin_get_user_by_openid', $user, $openid );
Description
Filter the result of a query getting a WordPress user associated with a recorded WeChat openID.
Parameters
$user
(mixed) The
WP_User
object if the user was found,false
otherwise.
$openid
(string) The openID used to search for the user
apply_filters( 'wp_weixin_pay_notify_results', (array) $results );
Description
Filter the results of handling a payment notification.
Not actually applied by WP Weixin directly itself, but only after a companion plugin has fired wp_weixin_handle_payment_notification.
See a WeChat Pay integration plugin skeleton for how to add payment notification results.
Parameters
$results
(array) An array of payment notification results. Structure of a result:
array(
'success' => false, // optional - (bool) wether the transaction to handle was found ; default false
'data' => $data, // required - (array) return value of WP_Weixin_Wechat::getNotify()
'refund' => false, // optional - (mixed) false if no refund needed, true or an refund message for the user otherwise ; default false
'notify_error' => false, // optional - (mixed) false if no error, true or an error message otherwise ; if truthy and pay_handler set to true, WeChat Pay API will continue to send notifications for the transaction ; default false
'blog_id' => $blog_id, // required for multisite, optional otherwise - (int) the ID of the blog where the original transaction was made ; default the return value of get_current_blog_id()
'pay_handler' => false, // optional - (bool) wether the result is for the callback registered in the WeChat Pay backend ; default false
/* More custom items can safely be added to the array */
);
apply_filters( 'wp_weixin_ecommerce_description', $ecommerce_description );
Description
Filter the description of the WeChat Pay Settings.
Parameters
$ecommerce_description
(string) The description of the WeChat Pay Settings (HTML).
apply_filters( 'wp_weixin_wechat_share_params', (array) $params, (mixed) $queried_object );
Description
Filter the parameters used to share a page.
Parameters
$params
(array) An array of parameters used to share a page. Structure of the parameters:
array(
'title' => $title, // title of the page to show on the sharing widget when shared in chats and moments timeline
'desc' => $description, // description of the page to show on the sharing widget when shared in chats
'link' => $url, // the destination URL
'imgUrl' => $img_url, // the thumbnail of the the sharing widget
);
$queried_object
(mixed) the WordPress object queried when loading the page.
The following template files are selected using the locate_template()
and included with load_template()
functions provided by WordPress. This means they can be overloaded in the active WordPress theme. Developers may place their custom template files in the following directories under the theme's folder (in order of selection priority):
plugins/wp-weixin/
wp-weixin/
plugins/
- at the root of the theme's folder
The available paths of the templates may be customised with the wp_weixin_locate_template_paths filter.
The style applied to all the templates below is enqueued as 'wp-weixin-main-style'
.
Templates index:
- wp-weixin-subscribe
- wp-weixin-browser-qr
- wp-weixin-auth-form-link
- wp-weixin-auth-page
- wp-weixin-mobile-auth-check
- wp-weixin-bind-form-link
- wp-weixin-bind-page
- wp-weixin-mobile-bind-check
- wp-weixin-public-info
- wp-weixin-account-form-password-notice
wp-weixin-subscribe.php
Description
The template of the page displaying the QR code to follow the Official Account. Used when "Force follow" is enabled in the settings.
$title
(string) The title of the screen presented to the user.
$message
(string) The message describing why the user sees this screen.
$qr_src
(string) The source of the QR code image.
wp-weixin-browser-qr.php
Description
The template of the page displaying the QR code when the website is accessible only through the WeChat browser.
Variables
$page_qr_src
(string) The source of the QR code image.
wp-weixin-auth-form-link.php
Description
The template of the WeChat authentication link.
Variables
$class
(string) The class attribute of the link.
$target
(string) The target attribute of the link.
wp-weixin-auth-page.php
Description
The template of the WeChat screen displayed for QR code authentication in classic browsers.
wp-weixin-mobile-auth-check.php
Description
The template of the WeChat mobile browser screen displayed when authenticating via QR code authentication in classic browsers.
Variables
$auth_qr_data
(array) Data related to the authentication. Value types and keys: (bool)
auth
, (int)user_id
, (array)error
, (bool|string)redirect
. Theredirect
value is not actually used for redirection by default on mobile (used after authentication on desktop).
wp-weixin-bind-form-link.php
Description
The template of the WeChat account binding link.
Variables
$link_text
(string) The text of the link.
$wechat_info
(mixed) An array of WeChat information if exists,
false
otherwise.
$class
(string) The class attribute of the link.
$target
(string) The target attribute of the link.
wp-weixin-bind-page.php
Description
The template of the WeChat screen displayed for WeChat account bindind in classic browsers.
Variables
$user_id
(int) The ID of the user to bind to a WeChat account.
$wechat_info
(mixed) An array of WeChat information if exists,
false
otherwise.
wp-weixin-mobile-bind-check.php
Description
The template of the WeChat mobile browser screen displayed when attempting to a WeChat account via QR code in classic browsers.
Variables
$bind_qr_data
(array) Data related to the account binding. Value types and keys: (bool)
bind
, (int)user_id
, (array)error
, (bool|string)redirect
. Theredirect
value is alwaysfalse
on mobile (populated and used after account binding on desktop).
wp-weixin-public-info.php
Description
The template to output the WeChat public information - notably used when calling wp_weixin_get_user_wechat_info with the $output
parameter set to false
.
Variables
$wechat_info
(array) The WeChat public information. Value are all of type (string), with keys:
nickname
,headimgurl
,sex
,language
,city
,province
,country
,unionid
.
wp-weixin-account-form-password-notice.php
Description
The template of the notice to show under the form to change the user account password.
The global variable wx
is already properly signed and initialised with the complete jsApiList
.
To use it properly, developers must:
- include their scripts in
wp_enqueue_scripts
action hook with a priority of6
or more, - make sure to set
wp-weixin-main-script
as a dependency - make sure "Enabled" is checked in WP Weixin Main Settings
In addition, a provided list of listeners may be subscribed to.
JavaScript listeners index:
- wpWeixinShareTimelineSuccessListener
- wpWeixinShareTimelineFailureListener
- wpWeixinShareAppMessageSuccessListener
- wpWeixinShareAppMessageFailureListener
Example for how to subscribe to the wpWeixinShareTimelineSuccessListener
listener:
window.wpWeixinShareTimelineSuccessListener( handleShareTimelineSuccess );
function handleShareTimelineSuccess( shareInfo ) {
// do something with the data
do_something( shareInfo );
}
window.wpWeixinShareTimelineSuccessListener( callback );
Subscribing to this listener will execute the callback
function after sharing the post on WeChat Moments succeeded.
Parameters passed to the callback
shareInfo
(object) The share information sent to the WeChat JS_SDK. Attributes are
title
,desc
,link
,imgUrl
.
window.wpWeixinShareTimelineFailureListener( callback );
Subscribing to this listener will execute the callback
function after sharing the post on WeChat Moments failed.
Parameters passed to the callback
shareInfo
(object) The share information sent to the WeChat JS_SDK. Attributes are
title
,desc
,link
,imgUrl
.
window.wpWeixinShareAppMessageSuccessListener( callback );`
Subscribing to this listener will execute the callback
function after sharing the post with WeChat "Send to chat" succeeded.
Parameters passed to the callback
shareInfo
(object) The share information sent to the WeChat JS_SDK. Attributes are
title
,desc
,link
,imgUrl
.
window.wpWeixinShareAppMessageFailureListener( callback );
Subscribing to this listener will execute the callback
function after sharing the post with WeChat "Send to chat" failed.
Parameters passed to the callback
shareInfo
(object) The share information sent to the WeChat JS_SDK. Attributes are
title
,desc
,link
,imgUrl
.