Docs

Cloud Compiler (Command-line)

You compile your app with the Lūt cloud compiler. The lut-foo command-line tool is available on npm, requires node.js, and is system-independent.

Install lut-foo

The lut-foo npm package is a command-line utility to build your app with the Lūt cloud compiler. First, install node.js, the server-side javascript platform. This should have included npm, the node.js package manager. Use npm to install the lut-foo package globally. From a command-line:

Unixen:
$ sudo npm install lut-foo -g

Windows (as administrator):
C:\> npm install lut-foo -g

Create Your Free Account

Use lut-foo to create your account and verify your email.

Unixen:
$ lut-foo register youremail@domain.ninja

Windows (as administrator):
C:\> lut-foo register youremail@domain.ninja

Retrieve the verification code from your email, then use it to call register again.

Unixen:
$ lut-foo register somecrazylongregistrationcode

Windows (as administrator):
C:\> lut-foo register somecrazylongregistrationcode

On success, the response will be your secret. Save this as you'll need to use it in your config.json file.

lut-foo usage

Follow a few simple steps to build your app with lut-foo:

  1. Create a new directory for your project (e.g. /apps/myBestApp) and cd into it.
  2. Run lut-foo once without any arguments to step through creating your config.json file.
  3. Place the rest of your project files in your project directory.
  4. Run lut-foo again to build your app on Lūt's cloud compiler.

lut-foo accepts 0 or 1 arguments. If invoked with 0 arguments, lut-foo checks for the presence of config.json in your current working directory; if found, it behaves as if you had called lut-foo build, otherwise it behaves as if you had called lut-foo init. If invoked with 1 argument, lut-foo takes one of the following verbs as an argument:

build
Submit the project in your current working directory to Lūt's cloud compiler, save the resulting packaged app locally.
init
Create a config.json file.
register
Register or confirm an email address as your clientID to use Lūt's cloud compiler. You can also request a new secret by following the same process as you did when registering. The register verb requires one argument:
email
If invoked with an email address, Lūt sends a confirmation key to the given email address. Invoke register a second time with this key to receive your secret.
confirmation key
If invoked with a confirmation key you received by email, register returns your secret.
Unixen:
user@machine /apps/myBestApp $ lut-foo init
user@machine /apps/myBestApp $ lut-foo build

Windows:
C:\apps\myBestApp\> node lut-foo init
C:\apps\myBestApp\> node lut-foo build

Project Files

Required Files

Each lut-foo project requires at least 3 files for an android project or 4-5 files for an iOS project. They must have these filenames:

icon1024.png
A 1024x1024 image in PNG format that serves as your app launch icon and splash screen.
config.json
config.json is a JSON formatted file containing key/value pairs that define paramters of your app.
(android.jks) or (ios.p12 and app.mobileprovision and maybe aps_production.cer)
Code signing keys. Two different files are required for ios builds, but only one for android. Do not lose these files.
android:
android.jks is the Java Keystore generated with keytool that you use to sign your android apps.
ios:
ios.p12 is the PKCS 12 file generated from your iOS App Development Certificate from the Apple Developer iOS Dev Center.
app.mobileprovision is the mobile provisioning file specific to your app that was downloaded from the iOS Dev Center. This latter file should be either AdHoc or Distribution depending on your build target.
aps_production.cer is the APNS Production certificate you generated for Push Notifications from the iOS Dev Center. Mandatory only if uses.push is true.
Optional Files

Several optional files allow you to have greater control over the look of your app. Any of these files may be omitted.

Default.png
A 320x480 PNG file to use as a splash screen on very low density iPhones.
Default@2x.png
A 640x960 PNG file to use as a splash screen on mid density iPhones.
Default-568h@2x.png
A 640x1136 PNG file to use as a splash screen on the iPhone 5.
Default-Landscape.png
A 1024x768 PNG to use as a splash screen on Landscape launches on low density iPads.
Default-Landscape@2x.png
A 2048x1536 PNG to use as a splash screen on Landscape launches on high density iPads.
Default-Portrait.png
A 768x1024 PNG to use as a splash screen on Portrait launches on low density iPads.
Default-Portrait@2x.png
A 1536x2048 PNG to use as a splash screen on Portrait launches on high density iPads.
splash.png
A 1536x2048 PNG to use as a splash screen on Android devices.

config.json

Though invoking lut-foo init will step you through creating a config.json file, you may wish to edit it manually. Possible keys are:

Required Keys
androidAlias
Mandatory if target is android. The alias to the signing key in your keystore file. A string.
androidKeypass
Mandatory if target is android. The password to the private key found in your keystore file to which androidAlias refers. A string.
androidStorepass
Mandatory if target is android. The password to your android.jks keystore file. A string.
The copyright information for your app. Any string.
appFilename
The filename of your app. Any string.
appID
The appID of your app assigned to you by Lūt. A string.
appName
The name of your app, as seen on the device. Any string.
appVersion
The version number of your app.
appleGroupIdentifier
Mandatory if target is adhoc or appstore and uses.push is true. Your Apple Group Identifier. Assigned to you by Apple.
appleStorepass
Mandatory if target is adhoc or appstore. The keystore password to your ios.p12 PKCS12 file.
baseURL
A string. A fully formed URL at which the content of your app resides.
clientID
Your clientID, assigned to you by Lūt. A string.
GCMSenderID
Mandatory if target is android and uses.push is true. Your GCM Sender ID (aka Google API Project ID). Assigned to you by Google.
GCMServerAPIKey
Mandatory if target is android and uses.push is true. Your GCM Server API Key (aka Google Server Application API Key). Assigned to you by Google.
secret
Your secret key for access to the Lūt API. A string.
target
Desired build target. Values are android (for all android builds), adhoc (for iOS Ad Hoc builds), or appstore (for iOS Distribution builds).
Optional Keys
admobID
The ID passed to AdMob for in app ads. For free accounts, our ID is used. Assigned by AdMob / Google Mobile Ads.
appAspectRatio
Aspect ratio to display your app. Values are portrait, landscape, or any (enables rotation along with appAutoOrients). Defaults to portrait.
appAutoOrients
Determines if app should be allowed to rotate with device. Values are true or false. If true, appAspectRatio should be any. Defaults to false.
hideStatusBar
Flags if the device OS status bar should be hidden when your app launches. Values are true or false. Defaults to true.
splashBG
The background colour to fill around your icon1024.png image when generating splash screens. A 6-digit hex code that has format #RRGGBB. Defaults to #FFFFFF.
uses
Which elements of the LUT Device API your app uses. uses is itself an object that contains key-value pairs where all values are true or false. Set only elements of the API that your app uses to true for enhanced performance. All elements of uses default to false except version. adverts is always true if you have a free account.
"uses": {
	"adverts": false,
	"barcode": false,
	"open": false,
	"push": false,
	"version": true
}

Device (Javascript)

The LUT object is defined by the platform and contains groups of functions to interact with native hardware features. It is accessible on every page loaded in your app.

LUT.barcode.scan

Puts your page in the background and initiates a fullscreen camera interface that scans for barcodes. The camera interface continues until either a barcode is found or the user cancels via a cancel button.

LUT.barcode.scan(encoding, callback)

callback(err, data)
encoding
A string to indicate the encoding to look for. Possible encodings are: ALL, EAN8, UPCE, ISBN10, UPCA, EAN13, ISBN13, I25, DATABAR, DATABAR_EXP, CODABAR, CODE39, PDF417, QRCODE, CODE93, CODE128.
err
Truthy if an error occurred or the user cancelled.
data
The code found, usually a string.

LUT.open

Opens the specified URL using the defined protocol via the native implementation. This is useful on iOS to open another app from your app by using the protocol registered with iOS for the other app. Android behaves similarly using the intent handler for the protocol. For example, to load a URL in the default native browser, use the HTTP or HTTPS protocols.

	LUT.open(url);
url
The url you wish to pass to be opened in another app. The protocol used will determine what app is opened, on iOS by the registered protocol handlers, and on Android by the registered intent handlers. The exact nature and format of the url varies by the receiving app. For example, some apps may be opened with filesystem relative urls.

LUT.push.registerDevice

Should be called after you have authenticated the user in your app. This associates the userID you specify with the device, so push notifications to the userID will then be received by this device.

LUT.push.registerDevice(userID, callback)

callback(err, data)
userID
The userID (or any unique identifier you want to use) to associate with the device.
err
Truthy if an error occurred.
data
Object: data.registered = true on success, data.message = string of additional information (unused, reserved)

LUT.push.onNotification

The callback passed is called after the app has gained focus as the result of the user responding to a push notification. This is not an event style handler; only the last callback sent will be called. The Lūt platform's payload delivery will also cause this callback to fire each time your app gains focus and is delivered a non-zero amount of pending messages, either as a result of a call to LUT.push.registerDevice or of being brought back to the foreground.

LUT.push.onNotification(callback)

callback(err, data)
err
Truthy if an error occurred.
data
Contains an array of message data passed in from push notifications via send.

LUT.push.unregisterDevice

Call to unregister a userID / device pair from push notifications.

LUT.push.unregisterDevice(userID, callback)

callback(err, data)
userID
The userID (or any unique identifier you used) to remove. If this userID was not previously linked from this device via LUT.push.registerDevice, no action will be taken.
err
Truthy if an error occurred.
data
Object: data.unregistered = true on success, false if the userID/device pair was not found.

LUT.version

Checks the version of the LUT platform with which the app was built, and also the latest version number of the platform.

LUT.version(callback)

callback(err, data)
err
Truthy if an error occurred.
data
Object: data.current = string, version on which the app was built, data.latest = string, latest available version or null if not available

Server API (REST)

The REST interface takes and returns JSON formatted data. The endpoint URL is
https://ajax.lutunlimited.com/command
Requests should be sent using the POST verb.

send

Sends a push notification to the specified list of userIDs. Immediate push delivery is not guaranteed by the underlying services, but typically arrives in less than a minute. When opened the callback specified by LUT.push.onNotification is called. Opens are tracked (subject to Internet connectivity) and can be viewed by calling report. Payload delivery is provided by the Lūt platform with a maximum payload of approximately 0.5MB.

Request:
{
	clientID: string,
	secret: string,
	appID: string,
	message: {
		title: string,
		ticker: string,
		text: string,
		data: { ... }
		userIDs: [string, ... ]
	}
}

Response:
{
	messageID: string,
	published: Number,
	invalidUsers: [string, ...],
	queueFull: [string, ...]
}

-or-

error object
clientID
Your client ID assigned by Lūt.
secret
Your secret used for authentication. Assigned by Lūt.
appID
The appID of the app to send the message to.
title
Title displayed on the mobile device of the push notification. Appears on all devices.
ticker
Ticker text displayed on Android notification area.
text
Additional text displayed on Android notification area.
data
Payload object containing arbitrary additional content.
userIDs
Array of strings of the userIDs you want the message sent to. The userIDs are the ones registered by calls to LUT.push.registerDevice.
messageID
The unique identifier for the message you just sent. Use this for calls to report to view receipts and opens.
published
A count of the valid unique IDs (not devices!) the message was sent to. This may be less than the number of IDs sent if there were duplicates or if any userIDs weren't registered.
invalidUsers
Array of strings of the userIDs to which a push notification could not be sent. This could be because the user has uninstalled your app.
queueFull
Array of strings of userIDs for which the pending message queue is full. We still attempt to deliver the push notification. Users reach this status at around 10,000 pending messages, you should not send more messages to this user.

listApps

Lists all the apps, and appIDs, you have. Use the appIDs for listMessages.

Request:
{
	clientID: string,
	secret: string
}

Response:
{
	apps: [ string, ... ]
}

-or-

error object
clientID
Your client ID assigned by Lūt.
secret
Your secret used for authentication. Assigned by Lūt.
apps
Array of appIDs.

listMessages

Lists all messages for the given appID.

Request:
{
	clientID: string,
	secret: string,
	appID: string
}

Response:
{
	messageID*: UTC_timestamp
}

-or-

error object
clientID
Your client ID assigned by Lūt.
secret
Your secret used for authentication. Assigned by Lūt.
appID
The application ID you want to list messages for.
messageID*
The fields are not messageID, but rather the actual messageIDs for each message. The value of each field is a Number representing the UTC timestamp the message was sent. Use the messageID for calls to report to view receipts and opens.

report

Lists all the opens along with their timestamps for the given messageID.

Request:
{
	clientID: string,
	secret: string,
	appID: string,
	messageID: string
}

Response:
{
	userID*: UTC_timestamp
}

-or-

error object
clientID
Your client ID assigned by Lūt.
secret
Your secret used for authentication. Assigned by Lūt.
appID
The application ID you want to list opens for.
messageID
The message ID of the message to list opens for.
userID*
The fields are not userID, but rather the actual userIDs for each open. The value of each field is a Number representing the UTC timestamp the message was opened.