Getting Started with Local Development

This guide describes how to start developing custom activities locally using Scandit Flow.

Custom activities are mobile solutions written in JavaScript or any other language that transpiles to JavaScript.
The JavaScript code of an activity runs in a web view environment in a native mobile runtime (provided by Scandit). The web view environment is similar to a Chrome or Safari browser on a mobile device, with the biggest difference being the addition of the Flow Mobile API, that makes it easy to work with various features of the Flow Platform (e.g., barcode scanning, database actions, data synchronization, sending emails, etc.), as well as native and platform-specific functions and elements exposed to the activity.

Creating a new activity and running it on the phone

Create a new activity

  • You will want to start by going to Activities on the left side of the Flow web dashboard where you can create a new activity using the "Run your own code" template.
  • After giving the activity a name and saving it, you will see the "Hello World" example code in the web editor, the most basic template that gets created with every custom activity.
  • Click the Publish all files button and select the Development group to see it running on your device after the next step. This pushes your activity to all the devices that belong to the group you specify.
  • You should see a success message saying that the activity has been released.

Connect your device

Now it's time to connect your device and run the activity that you just created.

  • Go to Connect devices and enter your email address, to which an email with an activation code will be sent.
  • Change the group of the device you just added, by clicking the icon and choosing development, so you can access the activities pushed to the development group. If you want to use another group, make sure that the device is assigned to the same group that you're releasing the activity to.
  • Next you will want to enter the activation code in the Flow mobile app (for iOS, Android), along with the email address that you used for connecting the device.

After logging in on your device, and thus finishing connecting your device, you should see your new custom activity in the activity list of the mobile app.

Developing your custom activity locally

You can develop the activity source code locally using your preferred text editor and any other tools that you might want to use.

You can either use the Flow Desktop App or sflow.

  • The Flow Desktop App is a graphical interface that makes it easy to handle everything around developing activities locally, including installing dependencies and running the local development server needed for devices to connect to your computer and make it possible to preview the activity without pushing it to Scandit Cloud. See Option 1 below.
  • sflow is a command line utility to help you serve the locally developed activity to your device. You need to handle installing it yourself through npm, along with node and git - this gives you the ability to handle git and the local development server (provided by sflow) yourself, which makes it possible to integrate it into a set of tools you already use (e.g. task runners, etc.). See Option 2 below.

If you want to get started quickly and don't need the additional flexibility offered by sflow, we recommend that you use the Flow Desktop App.

Option 1: Installing the Flow Desktop App

You can download the app for your platform of choice by navigating to Downloads on the Flow web dashboard. After the download has finished, install the app according to your platform.

Option 2: Installing sflow and the required dependencies

Requirements

To get started you need to follow these steps:

Installing Git

  • Download and install the latest version of Git (http://git-scm.com/downloads)
  • Check that git was installed properly by running git --version, it should print out the version of git that was installed, without any errors or problems.
  • Open a terminal or shell which has access to the git command and set your name and email
    $ git config --global user.name "John Doe"
    $ git config --global user.email johndoe@example.com
    If there are any errors or problems when installing git, refer to the git documentation.

Installing Node.js

  • Download and install Node.js (https://nodejs.org/en)
  • Check that it was installed correctly by running node --version and npm --version. These should print out the installed versions of node and npm, respectively. If there are any errors or problems, refer to the documentation provided by node or npm.

Installing sflow

  • Download and install sflow through NPM.
    $ npm install -g https://scandium.scandit.com/sflow/latest

If you see warnings related to compiling native modules, it means that you don't have the tools needed to compile node-gyp modules. You can ignore these warnings as sflow will use the JavaScript implementation of these functions instead.

If you run into permission problems, npm asking you to run the command again as an administrator, run the command again with admin-like privileges:

$ sudo npm install -g https://scandium.scandit.com/sflow/latest

Getting the "Hello World" example code to your local computer

Using the Flow Desktop App

After opening the app and logging in with the same credentials that you use to log in to the Flow web dashboard, you'll be presented with a list of the activities that you have created. Download the one that you want to work on locally. You can now edit the local code with your preferred text editor.

Using sflow

When you open the activity editor on the web dashboard (), you will see a link to the Git repository of the activity in the top right corner.

To get the code onto your computer, you need to cd or navigate to the folder you want to have your project in and run git clone <repository url>, passing in the repository url of the activity (without the <,>), and providing the username (email) and password you use to login to the Flow web dashboard. After that, you need to checkout the branch that corresponds to the group you pushed your activity and connected your device to. If you used the development group before, as explained by this tutorial, you need to run git checkout development from your project folder. You can now edit the local code with your preferred text editor.

Running the local development server

Using the Flow Desktop App

After downloading the activity that you want to edit locally, you can start the development server by clicking the start button located to the right of the activity.

Using sflow

Run the sflow watch command from the directory that the activity is located in.

By only running the command sflow, you can get more information about the options it provides. Running sflow watch will watch the files in your project and update the build (JavaScript, HTML and CSS) on your device.

sflow will initially show the IP address you can connect to from your device. Your computer needs to be accessible from the device, for example by being on the same WiFi network.

Available IP addresses:
192.168.202.182 (en1)

Connecting to the local development server from your device

On your device, go to the activity list and tap on the menu button in the top right corner.
Select Enable local development mode and provide the IP address specified by the Flow Desktop app or sflow.
After doing so, you should see Local Activity as the last one in the activities list. Choosing this activity will connect to the running local server and load the code from your computer.

Editing your code

Once you have your device connected to the Flow server, you should be able to see changes made to the CSS files immediately on your device. To see updates made to the HTML views or the JavaScript code, you need to restart the activity by pressing the back button and running the activity again. Alternatively, you can restart from the Flow Desktop App or you can specify the --restart option when starting the local development server with sflow to restart automatically when needed.

Let's make a quick change to the activity so you can see how the local development server automatically rebuilds the activity when the code changes.

Replace view.html:

<p>Hello World! Here is {{ template_variable }}!</p>

Replace the start function of the App in app.js:

...
this.start = function(){
    var view = Scandit.Ui.Views.load('src/views/view.html', {template_variable: 'Hello World'});
    view.set("template_variable", "Scandit");
};
...

Developing the UI of Flow Activities

Most of the UI in the activities is built using HTML and CSS, similarly to mobile web sites. Scandit exposes some native controls to the Flow Mobile API accessible from the activity, such as barcode scanner, map, alert, loading indicator, menu and toolbar buttons, etc. You can check out the API documentation for more details.

Publishing your code

Connected devices in Scandit Flow belong to one of the three deployment groups: development, testing or production. Each of these groups can have a different set of activities published to, using different versions.

When you write the code using the web editor you have to publish an activity to see the updated version on your device.
When you use the Flow Desktop app or sflow, it is not needed to publish the code to see the changes on your device, as you can use local development. Once you are ready with the changes to the activity and want to share them with a group of devices, you will have to follow the steps outlined below to push your activity to your desired group.

Publishing the code using the Flow Desktop app or git

The Git repository contains three branches, development, testing or production, relating to the three groups. When you push your changes to one of these branches the updated activity will be published to the devices that belong to that group.

You can push to your chosen branch either via the Flow Desktop app or git. If you use the Flow Desktop app, simply use the Push button and choose the groups that you want your activity to show up to. If you want to use git, you need to run the following command after committing your changes (where <group> is the name of the branch associated with deployment group that you're targeting, possible values are development, testing and production):

$ git push origin <group>

On your device, you'll get a push notification, informing you that an activity was updated. You can now run the updated activity from the activity list.

Using Git and the web editor at the same time

If multiple developers are developing the same activity simultaneously using Git and the web editor, it could lead to conflicts and is generally not advised. You should rather only use the web editor or local development.
In the web editor you will see conflict error messages and will be given an option to stash the changes on the a different stash branch. To use these changes you will need to merge and solve conflicts using normal Git commands.

Next steps

Congratulations, you now have set up local development on your machine and can edit the code of your activities, as well as preview the activity locally on your device and push it to a group of devices connected to your Flow account.

You might want to learn more about the Flow Mobile API in the API Documentation, or read one of our guides on different aspects of activities and how to develop them.
We recommend the following guides as your next steps to learn more about Scandit Flow Activities: