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

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 code
source\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.

image user permissions

Create App¶

Open the Platform Toolbar and select the App Manager menu.

image platform toolsbar

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.

image create app template

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 the App 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 can publish it, to make it available to other users. Apps in development status can become Published
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 in published status can be Un-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 the Update button. Users with developer permissions can in addition select to use any archived version of an App. Apps in archived status can be Published and Deprecated.
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 in deprecated status can be Archived.

Overview of App statuses¶

STATUS	ACTION	NEW STATUS
development	Publish	published
published	Un-publish	archived
archived	Publish	published
	Deprecate	deprecated
deprecated	Archive	archived