Starting Your First App

This guide shows you how to set up a project. If you are coming from any of the samples, note that (most of) these steps have already been done ahead of time.

Platform Compatibility

We test our SDK against the following platforms:

  • iOS
  • Android

The minimum version supported for each platform depends on the version of NativeScript. We support NativeScript version 3.x and above.

Add an App Backend

If you don't have an account on Kinvey yet, please signup before continuing.

In the Kinvey console, create a new app backend. If you are currently viewing another app backend, click the app's name in the left navigation, and the select "New App" in the menu.

On the app dashboard page, you will find your App Key and App Secret in the top right. You’ll need those to configure your app.

Create a NativeScript app

You can set up your app using NativeScript Sidekick or manually from the command line.

Using Sidekick

NativeScript Sidekick is a lightweight GUI client which runs on your desktop and is available for Windows, macOS, and Linux.

After you download and install Sidekick, you can start by creating a new Angular, TypeScript, or plain JavaScript app. You can also select from a set of Kinvey templates, which give you a head start with integrating your Kinvey backend. Continue to the NativeScript Sidekick documentation to learn how to use the tool.

Using the Command Line Interface

If you prefer to use command line tools, follow the NativeScript Getting Started Guide to set up the CLI.

When you create a new app from the command line, you have the option to use a template. The Kinvey templates are listed under the Samples DevCenter section.

Add Kinvey SDK

You can add the Kinvey SDK to your project in one of two ways: using the NativeScript package manager or manually using the SDK source code.

If you used a Kinvey template to set up your NativeScript app, you can skip this step. The Kinvey SDK is already added to your app.

Using Package

The Kinvey NativeScript SDK is available for easy installation on the NativeScript Marketplace. Use the following command to add the SDK as a plugin to your NativeScript app:

tns plugin add kinvey-nativescript-sdk

Using Source Code

The Kinvey NativeScript SDK is open source software. If you prefer to build your app against the SDK source code, you can follow the instructions in our GitHub repo to set up the SDK.

Configure Your App

To use the SDK, you need to initialize it with your App Key and App Secret.

import { Kinvey } from 'kinvey-nativescript-sdk';
Kinvey.init({
    appKey: '<appKey>',
    appSecret: '<appSecret>'
});
var Kinvey = require('kinvey-nativescript-sdk').Kinvey;
Kinvey.init({
    appKey: '<appKey>',
    appSecret: '<appSecret>'
});

Kinvey.init() also accepts the following options when initializing the SDK:

OptionDescription
appVersionSet a version for your app that will be sent as the header X-Kinvey-Client-App-Version on every network request.
defaultTimeoutSet the default timeout used for all requests. The value must be in milliseconds. The default value is 60000 ms (1 minute).

Customers with dedicated Kinvey instances and Progress Health Cloud customers need to set instanceId to the ID of their dedicated Kinvey instance to correctly setup the backend and Mobile Identity Connect API URLs for the library.

You can find your Instance ID on the dashboard of the Kinvey Console, next to your App Key and App Secret.

import { Kinvey } from 'kinvey-nativescript-sdk';
Kinvey.init({
    appKey: '<appKey>',
    appSecret: '<appSecret>',
    instanceId: '<instanceId>'
});
var Kinvey = require('kinvey-nativescript-sdk').Kinvey;
Kinvey.init({
    appKey: '<appKey>',
    appSecret: '<appSecret>',
    instanceId: '<instanceId>'
});

Example of an instanceId would be:

instanceId: 'kvy-us2'

Never use the Master Secret in client-side code.

Verify Set Up

Your app is now connected to Kinvey. The ping method, as shown below, will contact the backend and verify that the SDK can communicate with your app.

Kinvey.ping()
    .then((response) => {
        console.log(`Kinvey Ping Success. Kinvey Service is alive, version: ${response.version}, response: ${response.kinvey}`);
    })
    .catch((error) => {
        console.log(`Kinvey Ping Failed. Response: ${error.description}`);
    });
Kinvey.ping()
    .then(function(response) {
        console.log('Kinvey Ping Success. Kinvey Service is alive, version: ' + response.version + ', response: ' + response.kinvey);
    })
    .catch(function(error) {
        console.log('Kinvey Ping Failed. Response: ' + error.description);
    });

If the response just yields hello instead of hello app-name, please make sure you have configured your app. If the error yields This app backend not found, the app key and app secret you entered are incorrect.

Every App has an Active User

Your app will be used by a real-life human being. This person is represented by the Active User. This user object must explicitly be created, either with a username and password, OAuth sign-on (such as Facebook, Google+, LinkedIn, etc.), or Mobile Identity Connect. See the User Guide for more information.

What's next

You are now ready to start building your awesome apps! Next we recommend diving into the User Guide or Data Store Guide to learn more about our service, or explore the sample apps to go straight to working projects.

Related Samples

Got a question?