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
:
- Create a new directory for your project (e.g.
/apps/myBestApp
) andcd
into it. - Run
lut-foo
once without any arguments to step through creating yourconfig.json
file. - Place the rest of your project files in your project directory.
- 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. Theregister
verb requires one argument:
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
andapp.mobileprovision
and maybeaps_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 ifuses.push
istrue
.
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
isandroid
. The alias to the signing key in your keystore file. A string. androidKeypass
-
Mandatory if
target
isandroid
. The password to the private key found in your keystore file to whichandroidAlias
refers. A string. androidStorepass
-
Mandatory if
target
isandroid
. The password to yourandroid.jks
keystore file. A string. appCopyright
- 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
isadhoc
orappstore
anduses.push
istrue
. Your Apple Group Identifier. Assigned to you by Apple. appleStorepass
-
Mandatory if
target
isadhoc
orappstore
. The keystore password to yourios.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
isandroid
anduses.push
istrue
. Your GCM Sender ID (aka Google API Project ID). Assigned to you by Google. GCMServerAPIKey
-
Mandatory if
target
isandroid
anduses.push
istrue
. 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), orappstore
(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
, orany
(enables rotation along with appAutoOrients). Defaults toportrait
. appAutoOrients
-
Determines if app should be allowed to rotate with device. Values
are
true
orfalse
. Iftrue
,appAspectRatio
should beany
. Defaults tofalse
. hideStatusBar
-
Flags if the device OS status bar should be hidden when your app
launches. Values are
true
orfalse
. Defaults totrue
. 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 aretrue
orfalse
. Set only elements of the API that your app uses totrue
for enhanced performance. All elements ofuses
default tofalse
exceptversion
.adverts
is alwaystrue
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
- LUT.open
- LUT.push.registerDevice
- LUT.push.onNotification
- LUT.push.unregisterDevice
- LUT.version
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.