Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Quick Start

You can build Sparrow apps that will automate most of your development tasks by using the following steps.

1. Initial Requirements

2. Install Sparrow CLI

3. Develop an App

4. Test the App

5. Validate and Pack


Apps built on the SurveySparrow platform are compatible with the latest and immediately preceding version of the following browsers.

  • Google Chrome
  • Firefox
  • Edge
  • Arc

Inital requirements

Install NVM:

NVM (Node Version Manager) is a tool that allows you to easily manage multiple versions of Node.js on your system. Here are the steps to install NVM

On Mac OS:

  • Install brew using the commands given below. If you have already installed it, please skip this step.

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  • To Verify the installation

    brew --version

  • Install NVM via brew

    brew install nvm

  • Adding NVM to the shell profile. Follow the procedures in the image given below.

    nvm-installation

on Windows OS:

  • Installing Chocolatey package manager.
    • Launch Windows Powershell in Administrator mode.

    • Run the below command to install chocolatey.

      Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
    • If you face the issue - running the scripts is disabled on the system, run the following command Set-ExecutionPolicy Unrestricted on the windows powershell or command prompt in administrator mode.

  • Verify Chocolatey installation using the command given below. Verify NVM installation

    choco -v

  • Install NVM through the Chocolatey package manager.

    choco install nvm

  • Install via installers

    • Download the NVM Setup from here and Complete the installation process using the steps given here.

on Ubuntu:

  • If you don’t have curl installed already, install it.

    sudo apt-get install curl

  • Run the NVM installation script as shown below

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

  • The script clones the nvm repository to ~/.nvm, and attempts to add the source lines from the snippet below to the correct profile file (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).

    export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

  • When faced with any issues, follow the instructions given here For more details, refer to

Verify NVM installation 

nvm --version

Install Node:

  • To install Node.js 18 via nvm, follow the given steps.
nvm install 18
  • To use Node.js 18
nvm use 18
  • To verify that the node is installed correctly, run the following commands
node –-version

Install Mkcert

  • Mkcert is a tool for making locally-trusted development certificates. This allows for installing SSL certificate, thereby running the local SSDK application securely.
  • Mkcert does not have native support in Firefox. To proceed with your development work, you have the choice to either bypass security measures or manually integrate the certificate into your browser settings.

MacOS 

brew install mkcert

Windows - Open command prompt or Windows powershell in administrator mode and run the below command. 

choco install mkcert

Install the sparrow CLI:

  • To install the latest CLI version, run the following command.
npm install https://ssdk.surveysparrow.dev/ssdk.tgz -g
  • Run the following command to verify the CLI installation.
 ssdk version

image-1

Installation summary:

  • Ensure that the versions of the corresponding packages are as suggested or higher.
#for nvm -v
0.38.0
# for node -v
v18.12.0
# for npm -v
9.5.1
# for ssdk version
0.1.1

Develop an App:

  You can use the following steps to create an app that displays a sample text in the ‘Apps & Integrations’ section of setting page.

  • From the command line, navigate to the empty directory in which you want to create an app.

  • Run the following command: 
     ssdk create
  • Select first_app. A new app is created based on the first_app template.

image-1

The following directories and files are created as a result of the ssdk create command.

DIRECTORY/FILE DESCRIPTION
app/* Contains all the files required for the front-end component of an app. The JS file follows the ES5 standard.
app/index.html Contains files to render front-end components of an app. This is the first page that is loaded when the app is activated. When building an app, if the app uses Data methods, Request method, Installation Parameters, or Data Storage, update the index.html file with the following reference to client.js: <script src="https://ssdk.surveysparrow.dev/ssdk/2.0/assets/survey_client.js"></script>
app/scripts Contains all the Javascript files required to support the front-end functionality of an app.
app/scripts/app.js Contains the app logic to display.
app/styles Contains the styles required for the front-end components of an app.
app/styles/styles.css Contains CSS rules that are incorporated to HTML files, when referenced.
app/styles/images Contains images that can be used in the app.
app/styles/images/icon.svg Contains the app icon. The icon file should be of SVG type with a resolution of 64 x 64 pixels.
config/* Contains the installation parameters and oauth configuration files.
config/iparams.json* Contains all the installation parameters whose values are set when the app is installed. For more information, see Installation Parameters.
manifest.json* Contains details such as the platform version the app uses, product to which the app belongs, event listeners for serverless apps, SMI functions that can be invoked from the app’s front end component.
README.md Contains additional instructions, information, and code-related specifications pertaining to the app.

Note : When building an app, do not modify these file/folder names.

If you want to add serverless functionality to your app, add the server.js file to the server folder from your app’s root directory. Make sure you add appropriate configurations to the manifest.json file of your app

Test a front-end app:

  • From the command line, navigate to the directory that contains the app related files and run the following command.
ssdk run

  • If the ssdk run command causes an error regarding mkcert -install, then open up the text editor or the terminal in administrator mode and re-run the ssdk run command.

  • Upon running ssdk run command you will be prompted to install a certificate on your browser for establishing HTTPS connection between your local app and your browser.

image-5

  • After you agree to install SSL certificate on your browser, the SSL certificate will be installed on your browser and the app will start running on HTTPS.

image-6

   Example URL:  https://subdomain.surveysparrow.com/?dev=true

  • To allow the Chrome browser to connect to the test server that runs on HTTP,

    - Navigate to Settings -> Advanced -> Privacy and security -> Site settings -> Insecure content.

    - In the Allow section, click Add and enter the account URL. Example URL: https://subdomain.surveysparrow.com

  • To test and preview the app running in your local environment,
    • Go to Settings -> select apps & integrations. You can see your app displayed in the app listing section. Ensure that ?dev=true is appended to the url since the app is running in the local environment.

Validate and Pack:

To check if the app is error-free and package it for submission, follow the given steps.

  • To validate the code, run the following command. 
    ssdk validate [--app-dir DIR]

    Here, DIR is the relative or absolute path to the project directory. If there are errors in the code, corresponding violations are displayed.

  • To pack the app for submission, run the following command. 
    ssdk pack [--app-dir DIR]

    The command generates the dist/my_first_app.zip file.

  • To publish the app to the Sparrow AppNest, navigate to the Sparrow developer portal and upload the packed file.

Uninstall SSDK:

In case if you want to uninstall the ssdk do the following steps:

npm uninstall ssdk -g

rm -r ~/.ssdk

Any queries or issues?

If you are encountering any issues with SSDK CLI or anything related to AppNest, we will help you with all the necessary resources to resolve them as early as possible. So, please feel free to reach out to us through the below mediums.

  • Developer Community - AppNest has a vibrant community where you can raise your issue and interact with our support team to tackle it.

  • Email - We have yet another way for you to reach out to us. Send your queries to this mail - support@surveysparrow.dev and we look forward to improving your AppNest experience.