The MobileSmith Applet is a way to bring a little bit of the web to your native application. Unlike a simple link to a web page, Applets can run offline, interact with the native platform, and be configured through our web interface.
This page will take you through the process of creating a custom Applet, including how to host it, what features are supported, and where you can get the resources you need.
Applets are based on web technologies, so you can develop them in something as simple as Notepad or use more advanced tools such as Aptana Studio.
Applets need to be hosted online at a location that can be publicly accessed. Applets must be packaged in a certain way and while the format is simple, we also provide a PHP script (appletManager.php) that can easily update packages from a directory. Using a server with PHP installed will allow you to easily use this script to package the Applets. Any server side technology that supports zip archiving and JSON operations may be effectively used to automate the packaging process.
A Local Applet can be viewed as a special kind of HTML5-based package that is executed in a device’s web-view that has been enhanced with additional functionality. The additional functionality allows the HTML5 application to operate without an Internet connection, control the devices history behavior, and apply updates to functionality and options transparent to the app user.
In order for an Applet to work, certain files need to be present. You will be provided with helper scripts that make it easier to access the extra functionality the platform allows. At a minimum you need two files, an index and a config file. To use special features you will need additional files. These files interact with the MobileSmith Platform telling the devices when they need to update, where to find the package, and how to present customization options.
The Applet directory must be made available on your server. However you must provide a zip file that contains the contents of the directory. This compressed version is what will be downloaded by the device.
If you want to use the script provided to aid in managing Applets, create a directory that will serve as your Applets root. This area will contain the following: the Applet indexing and packaging script, an optional index that wraps the script, and folders representing the categories of Applets on your Applet server. Though not required, it is recommended that the Applets root directory be relatively short with no spaces in the path and easy to access from the Internet on a server that supports PHP.
A category directory contains multiple Applets. The purpose is to help organize your Applets so that ones with a similar theme can be grouped together. Each category directory must be writeable by the server in order for the packaging script to work. Although the final location of the Applet package is user configurable, the packaging script by default will generate the package next to the actual Applet directory. Though not necessarily required, it is highly recommended that a category directory not contain spaces.
The Applet directory contains the actual Applet code. You can usually visit the Applet directory in a web browser to help test the functionality and use your web browser’s inspection and debugging tools, though not all features that have been added by the MobileSmith Platform are available. Though not necessarily required, it is highly recommended that an Applet directory not contain spaces.
The Applet Manager is one of the helper scripts we provide to aid in creating and maintaining Applets. You may optionally include or use this file as an index in your Applets Root. The Applet
Manager provides several pieces of functionality provided the directory structure is as indicated above. You are free to modify the Applet Manager script but any updates made to the script will be based on the default directory structure.
First, the Applet Manager provides quick links to the directories for each Applet. You may use these links to look at the Applets in the web browser or to paste into the MobileSmith Platform.
Second, the Applet Manager provides automated packaging for the Applets. As long as the Category Directory is writeable, the script will read the Applet structure, write the file used to check package integrity, and appropriately compress the Applet for distribution.
Third, it provides links to the generated packages.
Fourth, it provides an “Update All” feature that can be used to refresh the packages for all recognized Applets.
You may create the Applet package file manually, provide it any name and store it anywhere accessible to the target device. However, by default, these are generated next to the Applet Directory by the Applet Manager. They have the same name as the directory with .zip appended to the name and are automatically updated by the script. In the configuration file, these are easily pointed to by using the “up a level” indicator, “..”. I will discuss how to indicate the location of these files later.
The zip itself is in standard .zip format. We do not support other archive formats such as bzip or RAR, and are instead aiming for maximum compatibility. The file contains an exact copy of the Applet Directory contents but by decreasing the number of requests that have to be made we make the process more efficient.
Because this is what is actually downloaded by the target device, you must make sure that whenever you update the Applet itself, you update this file to match those changes. If you forget to update this file, the device will detect a version change and download the old package and an additional indication will be required to apply the update.
Please note, if you create the Applet package file manually, make sure the applet files are located at the root of the zip file, not contained in a parent directory inside the zip file. Including the parent directory in the zip file will prevent the target device from successfully unzipping and accessing the applet files.
This is the configuration file that indicates when an Applet has been updated. The information here is essentially the descriptor that makes the whole Applet work with the MobileSmith Platform. The file contains a single JSON formatted object of Key-Value pairs. There are currently several properties supported, some of which are absolutely important to the functionality of the Applet.
The items should be keys with their corresponding values represented in JSON. Remember to escape special characters such as the single quote. This is a standard JSON file, not just ECMAScript notation, so please remember to use appropriate quotes when needed.
{ “title” : “Repayments”, “description” : “Repayment Calculator”, “version” : 1.0, “publisher” : “MobileSmith”, “changelog” : “Initial Release.”, “hasrequiresdata” : false, “author” : “name@company.com”, “zipfile” : “../Repayments.zip” } |
In order to improve the integrity of the Applets, mostFileList.js should include a JSON array of all files relative to the Applet directory that are required for the Applet to function completely. If you are using the Applet Manager, it will update this file for you when you generate the Applet package.
This file is required for iOS native integration. Include it in any HTML files that will be using iOS integration. This file is also required to be loaded before the helper script mostHelp.js, which is covered below.
This file contains helper scripts for integrating with native device functionality. These functions include identifying the device as Android or iOS, and pulling in the configuration and customization contained in the mostConfig.json and mostCustomizations.json files. Three key functions will help provide a native app experience when users interact with your applet. These functions depend on methods in
This file is actually generated by the MobileSmith Platform and loaded by the device, but you can create it manually in order to test customization options. This file is a JSON object of key-value pairs indicating the customization “name” and “value” fields.
{ “calcTitle” : “Borrowing Capacity Calculator”, “disclaimer” : “Whilst every effort has been made to ensure the accuracy of the calculators, the results should be used as an indication only.” } |
If you want your Applet to be customized from the MobileSmith Platform, you may provide a mostCustomizationOptions.json file. This file is interpreted by the platform and used to generate the final mostCustomizations that is delivered to the device. This file is a JSON array, containing JSON objects that describe the customization options.
Name
Value
Title
helpText
Type
[ { “value” : “#000000”, “helpText” : “Select a color to be used as the main text color in your Applet.”, “title” : “Text Color”, “name” : “foreground”, “type” : “color” }, { “value” : “My Awesome Firm”, “helpText” : “Enter your firm name to be displayed in the title of your Applet.”, “title” : “Firm Name”, “name” : “firmname”, “type” : “textbox” }, { “value” : “#000000”, “helpText” : “Select a color to be used for the title of your Applet.”, “title” : “Title Color”, “name” : “titlecolor”, “type” : “color” }, { “value” : “The calculations are for estimation purposes only and do not assure that you will get a loan at this rate.”, “helpText” : “Enter a text message to your app users.”, “title” : “Disclaimer Text”, “name” : “disclaimertext”, “type” : “textarea” }, { “value” : true “helpText” : “Check this box to include or exclude something.”, “title” : “Set Boolean”, “name” : “setBoolean”, “type” : “boolean” } ] |
You can send an email or text message from an applet using the default email or text messaging app on the user’s device with a simple “mailto” or “sms” link. Remember to URL encode the link string if you are setting a subject or body which could contain spaces, line breaks, or reserved characters. You can include the link in an HTML anchor element like so:
<a href=“mailto:noreply@myawesomecompany.com?subject=Hello%20World”>Mail</a> |
or
<a href=“sms:?Hello%20World”>Text Message</a> |
You can also trigger the link from Javascript like so:
window.location.href = 'mailto:?subject='+encodedSubject+'&body='+encodedBody; |
or
window.location.href = 'sms:'+phoneNumber+'?body='+encodedBody; |
[See Email Checklist Test Applet http://applets.mobilesmith.com/forms/emailChecklistTest.zip]
If your applet needs to send an email, but you cannot reply on the phone’s native email app, you can make use of a MobileSmith service to send the email. To make use of the service, you will need to acquire certain information from the mostCustomizations.json file as sent to the device when the app is built. These values are:
projectUrl : the URL of the MobileSmith platform where the app was built.
projectAPIKey: a unique identifier that ties the applet to a specific app on the MobileSmith platform.
You can find the Project API Key from the MobileSmith platform on the App Settings page of your project, which can be helpful during the development phase, but you should always look up these values using the mostHelp.getCustomizationsObject() helper method in the mostHelp.js file when you release your applet for use. The Project API Key can be reset from the App Settings page, and your applet will only get the updated key if it using the mostCustomizations.json file to look up the key. Please note: if the Project API Key is reset, you will not need to rebuild the app, but you will need to close the app (including running in the background) before the device will look up the new key.
To submit your request to the email service, you will need to make an ajax call similar to the following:
$.ajax({ method:'POST', headers: { 'projectAPIKey': mostData.projectAPIKey }, data:JSON.stringify(jsonData), contentType:'application/json', url:mostData.projectUrl + '/api/email/projectemail', complete: function(){ // Actions to take on completion. }, error:function(data, textStatus, errorThrown) { // Actions to take on failure, such as informing the user why their email could not be sent. var retVal = JSON.parse(data && data.responseText ? data.responseText : '{}'); var msg = (retVal.message || 'Could not send message'); mostHelp.mostDialog('Error sending email', msg, 'Okay'); }, success:function() { // Actions to take on success, such as informing the user that their email has been sent. mostHelp.mostDialog('Email Sent', 'Your email has been sent', 'Okay'); } }); |
{ "fromAddress”:senderEmailAddress, "toAddress”:recipientEmailAddress, "subject”:emailSubject, "messageType”:plainTextOrHTML, "message”:messageBody } |
If the email is not sent successfully, the service will respond with an appropriate status code and JSON (serialized in the responseText) containing a status of failure and a message explaining the error. For example:
{ "message": “Invalid sender email address“, "status": “failure” } |
If the email is sent successfully, the service will respond with a 200 status code and JSON such as the following:
{ "message": "", "status": "success" } |
[See Email Service Example Applet http://applets.mobilesmith.com/forms/emailServiceExample.zip]
Watch the short video below on how to create the Local Applet AppBlock.
|