WP Weixin - WordPress WeChat integration

• General Description
  • Companion Plugins
  • Important Notes
  • Registering a domain in the Official Account's backend
  • Overview
  • Object Cache considerations
• Settings
  • Main Settings
  • Multisite Settings
  • WeChat Responder Settings
  • WeChat Pay Settings
  • Proxy Settings
  • Miscellaneous Settings
• Multisite
• WeChat SDK
• Functions
• Hooks - actions & filters
  • Actions
  • Filters
• Templates
• JavaScript

General Description

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!

Companion Plugins

• 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.

Important Notes

• 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).

Registering a domain in the Official Account's backend

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 or https) - making sure to include the MP_verify_[some_code].txt files to the root of the website corresponding to the domain registered as instructed, accessible publicly.

Overview

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.

Object Cache considerations

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:

• W3 Total Cache
• APC Object Cache / APCu Object Cache
• Redis Object Cache

Settings

The following settings are available on the WP Weixin settings page.

Main Settings

Required settings below are the minimal configuration necessary for the plugin to have any effect.

Multisite Settings

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.

WeChat Responder Settings

WeChat Pay Settings

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).

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.

Proxy Settings

Depending on your server configuration, a proxy may be needed if WordPress is behind a firewall or within a company network.

Miscellaneous Settings

Multisite

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).

WeChat SDK

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 );
}

Functions

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

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

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

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

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 of WP_User objects if several matches exist, false otherwise.

wp_weixin_get_wechat

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

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

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

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 ; if false, the language will be switched only if "Browser language redirect" is enabled in WPML - default true.

Return value

(bool) Wether SitePress::switch_lang( $code = null, $cookie_lang = false ) was called.

wp_weixin_get_signed_package

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

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

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

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 to true, the link's markup - false otherwise.

wp_weixin_get_bind_link

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 to true, the link's markup - false otherwise.

wp_weixin_unbind

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

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.

Hooks - actions & filters

WP Weixin gives developers the possibilty to customise its behavior with a series of custom actions and filters.

Actions

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

wp_weixin_extensions

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.

wp_weixin_responder

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.

wp_weixin_save_access_info

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 and expiry.

wp_weixin_before_user_profile_wechat_info

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.

wp_weixin_after_user_profile_wechat_info

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.

wp_weixin_before_bind_account

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.

wp_weixin_after_bind_account

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.

wp_weixin_before_unbind_account

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.

wp_weixin_after_unbind_account

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.

wp_weixin_before_tabs_settings

do_action( 'wp_weixin_before_tabs_settings' );

Description Fired before outputting the tabs of the WP Weixin page.

wp_weixin_before_main_tab_settings

do_action( 'wp_weixin_before_main_tab_settings' );

Description Fired before outputting the main settings tab of the WP Weixin page.

wp_weixin_before_main_settings_inner

do_action( 'wp_weixin_before_main_settings_inner' );

Description Fired before outputting the main settings content on the WP Weixin page.

wp_weixin_after_main_settings_inner

do_action( 'wp_weixin_after_main_settings_inner' );

Description Fired after outputting the main settings content on the WP Weixin page.

wp_weixin_after_main_tab_settings

do_action( 'wp_weixin_after_main_tab_settings' );

Description Fired after outputting the main settings tab of the WP Weixin page.

wp_weixin_before_qr_tab_settings

do_action( 'wp_weixin_before_qr_tab_settings' );

Description Fired before outputting the QR code generator tab of the WP Weixin page.

wp_weixin_after_qr_tab_settings

do_action( 'wp_weixin_after_qr_tab_settings' );

Description Fired after outputting the QR code generator tab of the WP Weixin page.

wp_weixin_after_tabs_settings

do_action( 'wp_weixin_after_tabs_settings' );

Description Fired after outputting the tabs of the WP Weixin page.

wp_weixin_before_settings

do_action( 'wp_weixin_before_settings' );

Description Fired before outputting the settings on the WP Weixin page.

wp_weixin_before_main_settings

do_action( 'wp_weixin_before_main_settings' );

Description Fired before outputting the main settings box on the WP Weixin page.

wp_weixin_after_main_settings

do_action( 'wp_weixin_after_main_settings' );

Description Fired after outputting the main settings box on the WP Weixin page.

wp_weixin_before_qr_settings

do_action( 'wp_weixin_before_qr_settings' );

Description Fired before outputting the QR code generator on the WP Weixin page.

wp_weixin_before_qr_settings_inner

do_action( 'wp_weixin_before_qr_settings_inner' );

Description Fired before outputting the QR code generator box on the WP Weixin page.

wp_weixin_after_qr_settings_inner

do_action( 'wp_weixin_after_qr_settings_inner' );

Description Fired after outputting the QR code generator box on the WP Weixin page.

wp_weixin_after_qr_settings

do_action( 'wp_weixin_after_qr_settings' );

Description Fired after outputting the QR code generator on the WP Weixin page.

wp_weixin_after_settings

do_action( 'wp_weixin_after_settings' );

Description Fired after outputting the settings on the WP Weixin page.

wp_weixin_endpoints

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).

wp_weixin_handle_payment_notification

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.

wp_weixin_handle_auto_refund

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

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

wp_weixin_browser_page_qr_src

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.

wp_weixin_subscribe_src

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.

wp_weixin_follower_notice_title

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!".

wp_weixin_follower_notice

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.".

wp_weixin_auth_needed

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.

wp_weixin_debug

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.

wp_weixin_follower_welcome_title

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!'" where user_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 - default home_url().

wp_weixin_follower_welcome_description

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 - default home_url().

wp_weixin_follower_welcome_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 - default home_url().

wp_weixin_follower_welcome_pic_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 - default home_url().

wp_weixin_get_access_info

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.

wp_weixin_jsapi_urls

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.

wp_weixin_pay_callback_endpoint

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).

wp_weixin_settings

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.

wp_weixin_show_settings_section

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.

wp_weixin_show_setting

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.

wp_weixin_settings_fields

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.

wp_weixin_auth_redirect

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 is home_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.

wp_weixin_scan_heartbeat_frequency

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.

wp_weixin_qr_cleanup_frequency

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'.

wp_weixin_qr_lifetime

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.

wp_weixin_user_wechat_info

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.

wp_weixin_ms_auto_add_to_blog

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.

wp_weixin_ms_auth_blog_id

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.

wp_weixin_ms_pay_blog_id

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().

wp_weixin_locate_template_paths

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.

wp_weixin_get_user_by_openid

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

wp_weixin_pay_notify_results

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 */
);

wp_weixin_ecommerce_description

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).

wp_weixin_wechat_share_params

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.

Templates

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

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

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

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

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

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. The redirect value is not actually used for redirection by default on mobile (used after authentication on desktop).

wp-weixin-bind-form-link

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

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

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. The redirect value is always false on mobile (populated and used after account binding on desktop).

wp-weixin-public-info

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

wp-weixin-account-form-password-notice.php

Description
The template of the notice to show under the form to change the user account password.

JavaScript

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 of 6 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 );
}

wpWeixinShareTimelineSuccessListener

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.

wpWeixinShareTimelineFailureListener

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.

wpWeixinShareAppMessageSuccessListener

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.

wpWeixinShareAppMessageFailureListener

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.