4 Replies Latest reply on Jan 31, 2017 12:35 AM by RevolverRelayer

    First Launch Tutorial for Phonegap App


      I'm wanting to create a tutorial for my app. The first time someone installs the app it gives them a run down of how to use it.  I haven't been able to find any plugins or anything that gives suggestions on how to do this.  Anyone aware of anything?

        • 1. Re: First Launch Tutorial for Phonegap App
          kerrishotts Adobe Employee

          You'll need to do the tutorial using HTML, CSS, and JavaScript. In essence, you'd do it in roughly the same way you'd implement this for a website that could rely only on client-side storage.


          Of course, PG gives you more options for persistent storage, so you could indicate that the user has finished the tutorial using any number of means (localStorage -- be careful, not guaranteed to be persistent!, File API, App Settings plugin, etc.)

          • 2. Re: First Launch Tutorial for Phonegap App
            RevolverRelayer Level 1



            I'm intrigued


            localStorage -- be careful, not guaranteed to be persistent!


            Do you mean local SQL or key-value pairs - why would this not persist? Is local storage unreliable?



            • 3. Re: First Launch Tutorial for Phonegap App
              kerrishotts Adobe Employee

              So, If you're using Cordova storage plugins (File API, SQLite, etc.), you're safe (as long as you yourself store files in persistent locations -- avoid Library/Caches and tmp, for example).


              When I talk about localStorage, I'm referring to the HTML5 Storage APIs (localStorage, sessionStorage, Web SQL). The iOS webview (ignoring Cordova for now), by default, stores these in cache directories that are prone to being removed. In doing so, Apple has made it clear: localStorage isn't safe. It is intended for data that needs to persist longer than, say, sessionStorage, but there's no guarantee of how long that data will live. The intent is that localStorage be used more like a cache in the sense that if the data goes away, it's easy to recreate. I do use it for trivial things, such as when an app has a couple of settings that don't the user's data in any way (say, app theme -- this is trivial for the user to change). Other examples include locally downloaded copies of the user's data that can be downloaded easily in the future should the local data disappear. (For example, a book reader might download a copy of the ebook to WebSQL. If the copy disappears, the user can just download it again from the server.)


              Now, bring Cordova in to the equation. Cordova-ios does have code in place to mitigate this problem (files get backed up, the file locations are modified), but there are still lots of reports online that localStorage just up and disappears. I don't have intimate knowledge of the code and associated failure situations, but my guess is there are edge cases that trigger the data loss, and chances are good there is no good debugging data on user devices when this happens, so there's little help in tracking every possible failure point down. Since Apple's already made changes in how localStorage works, it's also possible that it might change again in the future, and let's face it -- what are the chances that all of your users would have an instant fix in hand that would prevent data loss?


              It's also worth considering that, beyond very simple settings, localStorage (excluding Web SQL) is really not that great in the first place. It's synchronous and slow, limited to 5MB, and isn't really key/value storage as much as key:string/value:string storage -- you can't store a native JS object, for example, without stringifying it first. Web SQL has a similar problem with quotas (IIRC, 50MB is the max), and it's deprecated as a standard now anyway, so you should defer to using SQLite plugin instead anyway (which has more options anyway, and no quota!).


              Since this is Apple's stance and there are so many reports of localStorage continuing to be flaky on both iOS and Android, my suggestion is this: keep important data that can't otherwise be recreated out of localStorage and Web SQL. If the data is important, store it using a Cordova plugin (File API, SQLite, keychain, app preferences, depending upon the data type and security needed).


              Hope that helps!

              • 4. Re: First Launch Tutorial for Phonegap App
                RevolverRelayer Level 1

                Thanks, Kerri, a very informative and clear explanation!