Getting Started¶
The following steps are required to create a Singular App:
- Download the App boilerplate to your local disk
- Create an App in your Singular account
- Deploy your App code
- Testing and debugging your App
- Publishing your App
Download the App boilerplate¶
The following commands will create a folder on your local disk and download the App boilerplate code. We recommend adding this folder to your source code management tool.
Open a console and type following commands:
C:\Users\tm\Singular Apps>singular createapp mySingularApp
Singular App – mySingularApp has been created
C:\Users\tm\Singular Apps>dir /S /B
C:\Users\tm\Singular Apps\mySingularApp
C:\Users\tm\Singular Apps\mySingularApp\deploykey.json
C:\Users\tm\Singular Apps\mySingularApp\source
C:\Users\tm\Singular Apps\mySingularApp\source\app.html
C:\Users\tm\Singular Apps\mySingularApp\source\icon.png
This set of commands creates the folder “mySingularApp” and clones the widget boiler plate into this folder.
Description of default files:
deploykey.json
: File containing the app deploy key.source\app.hml
: app source codesource\icon.png
: app icon in png format
app.html example for deployed use¶
<!DOCTYPE html>
<html>
<body>
<script>
var singularApp = null;
// Singular App SDK calls singularAppInit when opening the app
// and returns the Singular App object as parameter
function singularAppInit(app) {
// call your init function
initSingularApp(app);
}
// your init app function
function initSingularApp(app) {
console.log("initSingularApp - app =", app);
// check if app had been created
if (app) {
// app created successfully
singularApp = app;
// get composition object, output object, storage object, ...
// ...
console.log("singularAppInit: app created successfully - app =", app);
} else {
// app created unsuccessfully
// handle error here
// ...
console.error("singularAppInit: Error - err =", err);
}
}
</script>
</body>
</html>
app.html example for local testing and development¶
<!DOCTYPE html>
<html>
<head>
<!-- Load to use the Singular App SDK Library -->
<script src="https://app.singular.live/libs/singularapp/1.0.0/singularapp.js"></script>
<!-- Load the Firebase JavaScript Library -->
<script src="https://www.gstatic.com/firebasejs/4.9.0/firebase.js"></script>
</head>
<body>
<script>
var singularApp = null;
// Create Singular app with the virtual app key
SingularApp.createWithAppInstanceKey(
"your-virtual-app-key",
"https://app.singular.live/",
singularAppInit, // callback function
"your-singular-user",
"your-singular-password"
);
function singularAppInit(app) {
console.log("initSingularApp - app =", app);
// check if app had been created
if (app) {
// app created successfully
singularApp = app;
// get composition object, output object, storage object, ...
// ...
console.log("singularAppInit: app created successfully - app =", app);
} else {
// app created unsuccessfully
// handle error here
// ...
console.error("singularAppInit: Error - err =", err);
}
}
</script>
</body>
</html>
Creating an App Template in your account¶
Log into Singular.live¶
To create a App for Singular.live, login with an account that has developer permissions. To check your user permissions, open the User Administration
of your Singular account.
Create App¶
Open the Platform Toolbar
and select the App Manager
menu.
Create a new App by clicking the New App
button. Enter a name and a category for your App. The App name does not need to match the name of the folder used with the singular createapp
command. Nevertheless, we recommend using the same names.
Enable your App for a composition and an output channel¶
The Add composition
button allows to add one or more compositions to your created App.
By using the Add Output
button, you can select the output(s) for your App.
Deploying an App¶
Open the App Manager
and select your app. Copy the Deploy Key
from the App Details into the deploykey.json
file. The file should look like this:
{
"deploykey": "uS3bDUabcDnYlAZMO87OL2nBckvSIdmE"
}
Upload the App code to Singular using following command in the node.js console:
C:\Users\tm\Singular Apps>singular deployapp myFirstApp
-----------------------------------------------
Singular.live app deploy
Validating files in directory "source"
Creating zip file
Deploying app to Singular.live
App ID: 54 successfully deployed
C:\Users\tm\Singular Apps>
The deploy script will then read the deploy.json file, exract the deploy key, create a zip-file of the app sources and upload it to the Singular.live cloud. Your app then will be visible in the App Browser
when creating a new app instance.
Activate the
Show Dev Versions
checkbox in theApp Browser
to access the development version of your app.
The status of the Development
version of your App gets updated every time you deploy new sources for your App. Refresh the App Manager
and select your App to see and select your App to see the updated status.
Testing and debugging an App¶
To test your App, follow these steps:
- Open your user folder in the Dashboard. Navigate to
Apps
that are presented in your Assets. Choose and open the App you want to debug. - Use the browsers built in capabilities for debugging and optimizing your App.
Publishing an App¶
When the App is fully tested, use the Publish
function to make it available for other users.
The Publish
function creates an identical copy of the Development
version of your App and tags it as Published
. The Development
version gets increased by one.
Apps never get deleted from the Singular.live platform. They are always in one of the following states:
-
development: Every new App starts in the
development
status. Apps under development and can only be accessed by users with development permissions. Once your App is fully developed and tested, you canpublish
it, to make it available to other users. Apps indevelopment
status can becomePublished
-
published: A published App is available to all members of your account. Only one
published
version of a App exists at the same time. By default, always the latest published version will be used when creating an instance of an App. Apps inpublished
status can beUn-published
. -
archived: Apps automatically get archived when a new version is published. Existing App instances that use an older version of the App still will stay on this older version. A standard user can manually
update
the App in the App instance by selecting theUpdate
button. Users with developer permissions can in addition select to use any archived version of an App. Apps inarchived
status can bePublished
andDeprecated
. -
depreciated: An App is set to
Deprecate
status, when you want or need to force App instances to use and upgrade to the latest published version of an App. An App indeprecated
status can beArchived
.
Overview of App statuses¶
STATUS | ACTION | NEW STATUS |
---|---|---|
development | Publish | published |
published | Un-publish | archived |
archived | Publish | published |
Deprecate | deprecated | |
deprecated | Archive | archived |