The Weixin app for iOS will be gradually upgraded to the WKWebview kernel before March 1, 2017, which requires web developers to be prepared for website compatibility and adaptation in advance. If you have any questions, please contact us with the contact information at the end of the document.
# Background
WKWebView is a new component introduced by Apple in iOS 8. It is designed to provide a modern web browsing control that supports the latest Webkit functions, in order to free from the out-dated and user-unfriendly UILogView with a huge memory footprint. This new component uses the same Nitro JavaScript engine as Safari, which greatly increases the execution speed of page JS.
# Switching method
Weixin 6.5.3 for iOS supports developers to manually switch WKWebview and UIWebview, so that they can adapt WKWebview in advance.
Manual switchover entry:
On the Weixin chat list page, tap the plus button in the upper right corner, select Add Friend in the menu, enter the string ":switchweb" in the search box of the friend addition page, and then click the search button in the lower right corner of the virtual keyboard. After the switchover is successfully completed, you will be prompted that the currently used kernel is UIWebview or WKWebview.
Switchover verification method:
After successfully switching to WKWebview by running a command, you can verify whether the current webpage is using the WKWebview kernel in the following method.
Enter any webpage from any entry within Weixin. After the webpage is successfully loaded, slide down the webpage (or tap the menu button in the upper right corner of the webpage) to display the address bar. On the address bar, if its display starts with "This webpage is", WKWebview is being used. If the display starts with "Webpage is", UIWebview is being used.
How the page determines whether the currently used kernel is the webview kernel:
On the page, whether the current kernel is the webview kernel can be judged by the window.__wxjs_is_wkwebview variable injected by Weixin. As of Weixin 6.5.3 for iOS, WKWebview is used when window.__wxjs_is_wkwebview is "true" and UIWebview when "false" or "undefine".
Key points of frontend adaptation
The primary principle of adaptation: If you cannot distinguish between the new behavior of WKWebview or the abnormality of the original page caused by the internal logic of Weixin, you can use the test page to separately test in the WKWebview kernel in Safari and Weixin to quickly locate the cause to the problem.
# Adaptation instructions
After you switch to WKWebview, the Webview behavior in Weixin is highly consistent with that in Safari. The only difference is that Weixin JSBridge-related scripts will be injected to Weixin Webview. Therefore, pay attention to the following notes for adaptation:
Check whether the page is functioning properly.
Check whether the page screen adaptation is normal.
Check whether the page behavior is normal. For example, you can check whether the page logic is normal when a user taps the back button to return to the previous page when browsing a page.
Check whether the syntax used by the page is compatible.
Check whether JSAPI is working perfectly.
Check whether the logics of Cookie and LocalStorage are normal.
If the server has been configured to return the validity period of Cache-Control, you need to check whether the relevant logic is normal.
Under normal circumstances, no special adaptation is required for your page. However, if your page involves the following affected logics, you need to adapt and confirm according to the adaptation suggestions.
JSAPI-related adaptation
- Cache is no longer supported
Change: cache jsapi will be temporarily not supported in WKWebview.
Adaptation suggestion: All developers using this API can remove the page-related logic.
- The page previews an image through LocalID
Changes: JSSDK versions earlier than version 1.2.0 no longer support previewing images by using the localld returned by the chooseImage API, for example: "img src=wxLocalResource://50114659201332".
Adaptation suggestion: Directly upgrade JSSDK to the latest version of 1.2.0 to help the page automatically adapt, which however may not work in some scenarios. You can use it in this case. Directly obtain data via the <a href="http://mp.weixin.qq.com/advanced/wiki?t=t=resource/res_main&id=mp1421141115 "getLocalImgData"" target="_blank">getLocalImgData API.
(Currently, the available online JSSDK versions are 1.0.0 and 1.1.0. Update your version to 1.2.0, https://res.wx.qq.com/open/js/jweixin-1.2.0.js.)
- JSSDK is used, and wx.config is used for permission authorization. In this case, you need to pay attention to the problem of failed JSAPI calls
Change: WKWebview's internal implementation changes have led to some logical adjustments to page JSAPI permission management in Weixin. There is a small possibility that the authorization to JSAPI that was granted normally now cannot be obtained, resulting in the failure of calling JSAPI.
Adaptation suggestion:
For Weixin 6.5.1 for iOS, the following WKWebview issue is known for this version: the page uses History API pushState, popstate, and replaceState for HTML5 to control page navigation (typically a single app page) and uses JSSDK's wx.config to authorize JSAPI. In this case, there is a great possibility that JSAPI cannot be called without authorization. In version 6.5.1, if possible, the page can use the Anchor hash technique to replace the History technique to solve this problem.
The preceding problem has been fixed in Weixin 6.5.2 for iOS and later versions. However, it is not 100% guaranteed that there is no such problem in the page that uses the history or hash technique to change the navigation address of the page. Therefore, developers still need to pay attention to such problem.
Problems related to the Cookie and LocalStorage settings
After you log out of the Weixin account, all Cookie and LocalStorage will be cleared.
Page functionality depends on Cookie, or there is a logic related to Cookie. Changes to the WKWebview internal implementation will affect the logic related to the Cookie of the current page.
Change 1: Cross-domain access to Cookie Problem description: When you try to access page A, if page A references page B's resources (pages A and B have different domain names), page B is considered to be a third-party page. In this case, if you set Cookie on page B, it will hit the security policy under WKWebview to prevent third parties from setting Cookie across domains, causing exceptions. Adaptation suggestion: In WKWebview, Cookie configuration by third parties across domains is disallowed by default. For any information passed through Cookie, you can store the information that needs to be transferred through the business backend, provide the page with the encrypted code access_token corresponding to the stored information, and then add the access_token of your own business in the URL to transfer the information between pages.
Change 2: Native-layer Weixin network requests cannot read the cookie set in WKWebview, even if the domain name is the same. Problem description: If the resource or image storage server for pages relies on checking Cookie to return data, after switching to WKWebview, when you press and hold Save in Weixin or tap to preview the large image, the network request made by the native layer will not carry the complete Cookie configured, resulting in failure of image saving or preview. Adaptation suggestion: Cookie free is recommended for static resources. If you do have information to be transferred, you can store the information to be transferred through the business backend, provide the page with the encrypted code access_token corresponding to the stored information, and then add the access_token of your own business in the URL to transfer the information between pages.
Except for the preceding two cases, developers do not have to worry about the loss of Cookie in other situations, because all requests will carry the complete Cookie.
Page video playback in small windows
Change: In Weixin 6.5.3 for iOS or above, Webview supports small-window playback by default.
Developers need to pay special attention that small-window playback requires the frontend to adapt to iOS 10 and earlier versions.
Adaptation suggestion: You must set the video tag exactly in the same way as below to be compatible with different iOS versions.
<video webkit-playsinline playsinline> </video>
The page behavior of WKWebview is identical to that of Safari, which will cause the page logic that relies on the UIWebview page behavior invalid or abnormal. (In this case, after the test page is implemented, respectively verify this problem in Safari and Weixin WKWebview according to the business logic.)
In Safari or Weixin WKWebview, after page A jumps to page B and then returns to page A, Script and Ajax are not re-executed (nor page reload is triggered), but events including pageshow and pageHide are triggered.
In Safari or Weixin WKWebview, after the page pops up the input keyboard, the resize event of JQuery is triggered, which however is negative in UIWebView.
In Safari or Weixin WKWebview, the window unload event can only be triggered if the page is refreshed but not in the case of existing the page or redirecting to another page.
In Safari or Weixin WKWebview, in rare cases, the page tapping event of certain special implementations are invalid.
If any of the preceding problems is involved or encountered, ensuring the compatibility with the Safari behavior prevails.
# Other problems
When the page customizes the standard reload method or function, ensure that it does not conflict with the JSBridge-related methods injected into the Weixin Webview; otherwise, it will cause the page to behave abnormally in Weixin.
It is strongly recommended not to set Cache-Control properties for HTML page files without ensuring that the page caching policy and logic are identical with server logic (except for HTML-type pages, other resources or scripts referenced by the page can be set according to their own business).
Typical case:
When you access page A.html for the first time, you are redirected to A1.html?uid=111 via a server-side 301 redirect. In this case, set Cache-Control: max-age=60, and the uid parameter of A1.html is 111, which was set by the server (at this moment, A1.html has been cached by the app.) When you access page A.html for the second time, you are redirected to A1.html?uid=222 via a server-side 302 redirect, in which case the uid parameter of the A1.html page is 222. Then, the app with the full link parameter queries whether the server cache is available, and the server returns that cache 304 is available, but the app-cached A1.html full link carries a uid of 111, and therefore the data cannot be found locally and the page will fail to be loaded.
When you are using WKWebView, the method of changing the native title multiple times via document.title in a single-page app will be invalid. This problem will be fixed in the new version to be released by Weixin in March.
In WKWebView, if smethor='post' and target='_blank' for form, the post data of a network request will be lost during submission.
The solution is to judge whether, in Weixin, the methord value is 'post' for form. If yes, change the target value to '_self'.
# Contact us
If you have any questions or encounter any problems during the adaptation process, please provide the detailed description of the problem and email us at wx_wkwebview@qq.com. We strongly recommend that you attach the link to the problematic page and show us how to reproduce the problem.