Document iOS WKWebView problems and workarounds

[nolanlawson]

(Follow-up to #5078.) We need to add this to the list of common errors, because it's going to affect everybody who's using Cordova these days.

Facts: DOM Exception 18 is thrown when trying to access WebSQL in two cases:

1. not enough storage
2. using WKWebView rather than UIWebView, since storage is set to 0 under the hood (i.e. it's disabled). WebKit issue.

Facts: WKWebView is now recommended in Cordova, and is commonly in use as of Cordova 4+ due to the performance boost relative to UIWebView. This also applies to Ionic/PhoneGap/etc.

Fact: WKWebView is now also used in Chrome, Firefox, and Opera for iOS, since they are not truly separate browsers but are instead wrappers around WKWebView.

The only workarounds for PouchDB as of right now are:

• FruitDOWN which is slow but gets the job done. Also it's apparently a bit buggy due to Apple's IDB implementation; there are quite a few open issues related to iOS and Safari.
• SQLite Plugin 2 which doesn't fix the Chrome/Firefox/Opera issue but does fix the Cordova/PhoneGap/Ionic issue. Slower than WebSQL, but faster than FruitDOWN. Also avoids "you ran out of storage" issue because it uses native SQLite.

If somebody would take this braindump of information and convert it into a readable section in the "common errors," I would be eternally grateful!

[nolanlawson]

BTW the way to fix this issue is pretty easy: just go to http://pouchdb.com/errors.html, click the pencil, and add a new section! Ideally it should go somewhere near the top because I bet a lot of people are going to run into this.

[nolanlawson]

Also note I don't recommend SQLite Plugin 1 anymore because we couldn't keep up with breaking changes, but I'm happy to mention it for folks who need features lacking in SQLite Plugin 2 (e.g. encrypted databases).

[mhartington]

Facts: WKWebView is now recommended in Cordova

I do want to add to this. Even though WKWebview is usable through cordova, it still isn't a default in Cordova. Most users who report using WKWebview either are using the WKWebView from telerik or the very experimental cordova wkwebview. Both of which need a small server running to be able to do anything with modern JS frameworks and both of which suffer from issues due with the web views limitations.

Not taking away form anything, just clarifying the point about cordova/ionic.

[nolanlawson]

Ah interesting, I assumed it was recommended at this point, given the large number of issues we see filed about it. For the fileserver issue, though: I thought the file:// problem was fixed in iOS 8.3 so you didn't need a server anymore?

[nolanlawson]

Ah nevermind, read a bit more in the README:

In iOS 9, Apple has fixed the issue present through iOS 8 where you cannot load locale files using file://, and must resort to using a local webserver. However, you are still not able to use XHR from the file:// protocol without CORS enabled on your server.

Yikes. 😓

[mhartington]

Yeah, thats the big problem with WKWebview for us right now.

[nolanlawson]

This has been fixed in WebKit master and should be available in the next version of iOS. So it's probably pointless to add any documentation about this; anyone interested in the bug will hopefully find this Github issue or other resources to answer their question.

WebKit issue: https://bugs.webkit.org/show_bug.cgi?id=137760

[mattlanham]

@mhartington It seems as though this is the default for Cordova OSX also? Which I assume is using WKWebview by default?

[simonaberry]

Interestingly I have the DOM Exception 18 on Safari on OS X (El Capitan) when browsing to a url that had a FRAME FORWARD to the actual hosted site.... changing the forward to a normal (header) redirect fixed the issue

[ozexpert]

Getting this when doing (pouchdb ver 5.4.5)

var localDB = new PouchDB('dbname');

ERROR: WebSQL threw an error Error: Error code 14: unable to open database file
with Ionic's wkwebview plugin
https://github.com/driftyco/cordova-plugin-wkwebview-engine

[nolanlawson]

@ozexpert WKWebView will not support WebSQL until Safari 10. You must use the SQLite Plugin, this is also recommended: http://github.com/nolanlawson/pouchdb-adapter-cordova-sqlite

[fabionpinheiro]

@nolanlawson In Ionic 1 + PouchDB 5.4.5 + iOS + WKWebView plugin, I'm trying:
1 - Install cordova-plugin-sqlite-2 1.0.4 and when try open database
var localDB = new PouchDB("localDB", {adapter: 'websql'}) I get this error:
{"status":500,"name":"web_sql_went_bad","message":"unknown","reason":"SecurityError: DOM Exception 18"

2 - Then, I downloaded the pouchdb.cordova-sqlite.js from https://npmcdn.com/pouchdb-adapter-cordova-sqlite/dist/pouchdb.cordova-sqlite.js and include this js in my index.html:<script src="lib/cordova-plugin-sqlite-2/dist/pouchdb.cordova-sqlite.js"></script>
When open my database:
var localDB = new PouchDB("localDB", {adapter: 'cordova-sqlite'}) I get this error:
Error: Adapter is missing

I have a database > 35mb, and without cordova-plugin-sqlite-2 I get the error of space when I synchronizing.

[guyromb]

@fabionpinheiro I think you experience the same issue that I had. Which is that the sqlite js file is loaded after angular, pouchdb etc.

[fabionpinheiro]

@guyromb I've tried many ways:
1 -

<script src="lib/pouch-db/sqlite-plugin.js"></script>
<script src="lib/ionic/js/ionic.bundle.js"></script>
<script src="cordova.js"></script>

<script src="lib/pouch-db/pouchdb-5.4.5.min.js"></script> 

2 -

<script src="lib/ionic/js/ionic.bundle.js"></script>
<script src="cordova.js"></script>

<script src="lib/pouch-db/sqlite-plugin.js"></script>
<script src="lib/pouch-db/pouchdb-5.4.5.min.js"></script>

Can you send me an example? From index.html order import and app.js with Pouch Instance like "var localDB = new PouchDB("local.db", {adapter: 'websql'});"

[nolanlawson]

@fabionpinheiro It's not enough to just include the script tag. You have to also explicitly register the plugin. See "not using npm?" under here: https://github.com/nolanlawson/pouchdb-adapter-cordova-sqlite#usage

[fabionpinheiro]

@nolanlawson I must include both in index.htlm? Ex:

<script src="lib/pouch-db/sqlite-plugin.js"></script>
<script src="lib/pouch-db/pouchdb.cordova-sqlite.js"></script>

<script src="lib/ionic/js/ionic.bundle.js"></script>

<script src="cordova.js"></script>

<script src="lib/pouch-db/pouchdb-5.4.5.js"></script>

Can I put the PouchDB.plugin(PouchAdapterCordovaSqlite) inside $ionicPlatform.ready(function() {... ?

Is there a detailed example ?

[nolanlawson]

You can put PouchDB.plugin(...) anywhere, yeah. I didn't create a sample app, no, but basically:

<script src="lib/pouch-db/sqlite-plugin.js"></script>
<script src="lib/pouch-db/pouchdb.cordova-sqlite.js"></script>
<script src="lib/ionic/js/ionic.bundle.js"></script>
<script src="cordova.js"></script>
<script src="lib/pouch-db/pouchdb-5.4.5.js"></script>
<script>
  PouchDB.plugin(PouchAdapterCordovaSqlite);
  var db = new PouchDB('foo.db', {adapter: "cordova-sqlite"});
</script>

[fabionpinheiro]

@nolanlawson Thanks for help, now it's working!
I had made several errors, and I realized seeing this tutorial: http://gonehybrid.com/how-to-use-pouchdb-sqlite-for-local-storage-in-your-ionic-app/

The right is (ionic 1):
1 - In index.html, just insert the pouchdb.js (in this example I not used pouchdb.cordova-sqlite but only automatic WebSQL [sqlite-plugin:true when there is])

<script src="lib/pouch-db/pouchdb-5.4.5.js"></script>

2 - Create the PouchDB instance in $ionicPlatform.ready inside your controller (
I was creating in app.js out and this time , sqlite-plugin was not yet recognized and generated all errors)
Ex:

app.controller('MyController......
     $ionicPlatform.ready(function() {
          var dbLocal = new PouchDB("local.db", {adapter: 'websql'});
          ...
     });

3 - Now, I can download and work with my PouchDB >50mb in iOS perfectly.