Web apps and HTML content guidelines

What's in it for you

You can present your content in an awesome way to really impress customers and prospects. By building interactive HTML5 Web apps to use within Showpad, you can guide your sales reps and their prospects in an interactive way. The following guidelines should be followed for optimal use of this HTML5 content in Showpad.

View an example

Key benefits

• Create customized HTML web apps that fit your sales needs.
• Impress customers and prospects
• Create interactive tutorials and conversations
• It works cross-platform
• Use the app offline, if all resources are available in the archive

You need this to succeed

• HTML5 knowledge
• Content to use in your custom web app
• Knowledge how to use Javascript, CSS, memory, and image handling
• Developing tools, like XCode (iOS), to check memory usage of your HTML app
• File size limit for Web apps and HTML apps is 4GB

The quick way to awesomeness

• Only HTML5 with Javascript, CSS, and images is supported
• Dynamic programming languages like Ruby, PHP, and .NET are not supported
• Flash is not fully supported on all platforms and should be avoided
• Avoid spaces in file and folder names
• Compress all files used by the web app in a ZIP file
• Put the index.html in the root folder of the ZIP
• Don't use iFrames in your application
• Upload your HTML. zip to your Showpad Library
• We recommend using HTTPS in all hyperlinks
• Always consider the memory limits of mobile devices
• See the W3C best practices for developing web apps

See this step by step

General

Only HTML5 web apps (using Javascript, CSS, HTML, images, ...) are supported. Dynamic programming languages like Ruby, PHP, .NET, etc require specific server software and will not run in the Showpad app.
Flash is not fully supported since it's an older technology and that may result in the pages not displaying as expected.

To prepare your web app for Showpad, compress all the files of the app into a .zip file and make sure there is an index.html file in the root or root folder. So the "main" HTML file should be called "index.html". Showpad will unpack the zip and process the web app to generate a thumbnail and make it ready for our apps. The thumbnail is white when the index.html file is empty. You can solve this by having an image in the HTML-content package that is visible the first few milliseconds, like a loading screen, and then is switched around for the actual content. We advise you to include all files used by the app (Javascript, CSS, images, ... ) in the .zip file so that the app will run properly whether there is an internet connection or not.

When you are ready, upload your HTML .zip file to your Showpad Library. Read more about how to do that here.

It is possible to run web apps inside Showpad even when there is no internet connection. The requirement for this is that all resources are available in the zip archive.

To see useful statistics about HTML5 app usage in Showpad's Web app, you can use Google Analytics to give you powerful insights. HTML content is requested over HTTPS, so be sure not to use HTTP as source script, since this will keep the app from loading correctly on most browsers.

In order to make the Google Analytics work in HTML5 apps on both the Web App and our mobile apps, you have to use the following:

// Create the tracker
ga('create', 'UA-ABCDE123465-1', 'auto');

// Don't let the tracker check the protocol
ga('set', 'checkProtocolTask', null);

// Don't let the tracker check the storage
ga('set', 'checkStorageTask', null);

// Don't let the tracker check the history
ga('set', 'historyImportTask', null);
ga('send', 'pageview', '/about');

Note: Change the UA ID with your company's property number.

You can also use Google's gtag.js service. To learn more about this, you can find the information here:

• How to use global site tag (gtag.js)
• How to go from analytics.js to gtag.js

General information can be found on Google's developers site. 

• Showpad can be accessed on iOS, Android, browser, and Windows (8.1+). This means the web app should fit multiple screen sizes, so using a responsive design is a good idea. The technologies used should fit these devices. On iOS/Android we use the standard web kit (Safari/Chrome). Showpad Web supports Edge, Chrome, Safari, and Firefox. For specific Windows guidelines, click here.
• Cross-domain Javascript loading might cause problems. Check Workaround.

On iOS there is an icon top left to enable the Showpad navigation to quit the web app. This means that this space should be reserved for that button and no action objects of the web app itself.
Please see this article for the full report on js functions we offer in HTML content.

It is possible to use local storage to save the state of a web app, so you can leave the app and come back to that state. Think of a filled in form, a language selection, etc.

When developing your HTML5 file, you should keep in mind that you cannot use iFrames for internal links since they will not work on the iPad.

• Webview element.
  When creating HTML content, also known as Web apps, that will be used in the Showpad Windows app, keep the following in mind that the windows store app uses the webview element (https://msdn.microsoft.com/en-us/library/windows/apps/dn301831.aspx) to display the HTML app.
  On Windows 10, some JS functions might be blocked. Check your logs to make sure they have enough permissions to be executed.
  
  The full app is first downloaded to the device and then loaded from disk using the ms-local-stream protocol, so all URI’s will start with ms-local-stream://. If you use angular you need to make sure that angular treats this as a safe protocol in its compile provider. If you do not do this angular will treat these URI’s as unsafe and prefix them with ‘unsafe:’ causing the webview element to not being able to load the requested item.
• Touch events
  See this blog for more info on what to take into account for touch events for the Metro Mode on Windows.

For utilization in the Showpad web app, please use the <a href=“”> tag method for asset links.

For use in the Showpad web app, please use the <a href=“”> tag method for hyperlinks. 
Also keep in mind that Showpad loads content over the https protocol and hyperlinks will also need to be loaded over https.
Also keep in mind section 2 about script source when you're linking to external pages.

• Know your hardware limits, it's not a spaceship you're running the code on.
• Know your external libraries, they provide you with easy to use APIs, but they might come with the cost of performance when not used correctly -> jQuery: `$()` is expensive, cache your selectors, chain your action/methods.
• Don't use JS animations and setTimeout, either use CSS animations (preferable 3d, so the GPU takes over the calculations, not the CPU) or use requestAnimationFrame.
• Keep your DOM as clean as possible. Hide/remove elements you are not using.
• Preloading assets are only interesting when they are coming from the network, not when they are stored on the device, also don't keep them in your DOM and make sure they have the right cache headers (or you won't be doing any preloading at all)
• Test inside Showpad.
• Don’t develop for a fixed viewport, not all devices are 1024*768 and devices can be rotated. If the app you're developing needs to be user landscape or portrait, be sure to add a message when used incorrectly.
• When sharing HTML content to a client (collection viewer), the HTML content will be shown in an iframe, make sure your viewport dimensions and overflow is set up correctly
• When implementing a button that does a location.reload(), using a click handler in JS, this will not work on the Web App. From inside the iframe try setting 'document.location.href = ' instead of window.location.reload()
• We recommend using HTTPS for HTML apps communicating externally on iOS. If you have issues with adapting to this, we recommend you to update to iOS version 10.1 or later. To make sure these URLs and HTML Apps work on iOS, we added an exception to allow HTTP communication in our web views. This exception only works from iOS version 10.1.
  On iOS 10.0, HTTP URLs or HTML apps that use HTTP for loading external resources will result in blank or half-loaded pages.
• We use WKWebview to embed content in our iOS app.
• Using the extension "index.htm" does not work and you should use .html instead.
• Avoid using shortcut folders (symlinks) in your site structure.