Getting Started

The content in this guide refers to the newly released version 3 of the library. You can still access the version 1.x guides here.

Version 1.x is now deprecated. We will continue to support 1.x through March 31, 2017 (End of Support - EOS). If you are currently using 1.x in your apps, you will need to upgrade your apps to 3.x before the EOS date. We have created a migration guide to help you.

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.

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.

Platform Compatibility

  • AngularJS

    • AngularJS (>= 1.2.1)
    • Ionic (v1.x)
  • PhoneGap

    • The AngularJS library is compatible with PhoneGap.
  • Browsers

    • Chrome - version 50 and above
    • FireFox - version 45 and above
    • IE - version 11 and Edge
    • Safari - version 10 and above

Add Kinvey SDK

You can add the Kinvey SDK to your project in one of two ways - using the package we ship, or using the source code.

Using Package

Add the following line of code after loading AngularJS.

<script src="//da189i1jfloii.cloudfront.net/js/kinvey-angular-sdk-3.5.2.min.js"></script>

Using a protocol relative URI means the library will be served using the same protocol (HTTP or HTTPS) as your index.html.

Using Source Code

Kinvey Javascript SDKs are now open source. If you prefer to compile your app against the SDK source code, you can follow the instructions on our github repo to set up the SDK.

Configure Your App

To use the library, you need to initialize it with your App Key and App Secret. The returned promise fulfills with the active user.

The documentation demonstrates how to use $kinvey as part of an AngularJS module. Depending on your use case, you can also use $kinvey inside services, factories, and controllers. See the AngularJS documentation on how to inject dependencies.

var initialized = false;
var app = angular.module('myApp', ['kinvey']);
app.run(['$kinvey', '$rootScope', '$location', function($kinvey, $rootScope, $location) {
  $rootScope.$on('$locationChangeStart', function(event, newUrl) {
    if (initialized === false) {
      event.preventDefault(); // Stop the location change

      // Initialize Kinvey
      $kinvey.initialize({
        appKey: '<appKey>',
        appSecret: '<appSecret>'
      }).then(function() {
        initialized = true;
        $location..path($location.url(newUrl).hash); // Go to the page
      }).catch(function(error) {
        // ...
      });
    }
  });
}]);

$kinvey.initialize also accepts the following options when initializing the library:

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.

Dedicated Kinvey customers, you'll need to set the API host name for the library to your dedicated Kinvey host name. You can find this host name on the dashboard of the console, next to your App Key and App Secret:

var initialized = false;
var app = angular.module('myApp', ['kinvey']);
app.run(['$kinvey', '$rootScope', '$location', function($kinvey, $rootScope, $location) {
  $rootScope.$on('$locationChangeStart', function(event, newUrl) {
    if (initialized === false) {
      event.preventDefault(); // Stop the location change

      // Initialize Kinvey
      $kinvey.initialize({
        apiHostname: '<my-subdomain>.kinvey.com',
        micHostname: '<my-subdomain>-auth.kinvey.com',
        appKey: '<appKey>',
        appSecret: '<appSecret>'
      }).then(function() {
        initialized = true;
        $location..path($location.url(newUrl).hash); // Go to the page
      }).catch(function(error) {
          // ...
      });
    }
  });
}]);

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.

var app = angular.module('myApp', ['kinvey']);
app.run(['$kinvey', function($kinvey) {
  // ...

  $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.

How to use in a PhoneGap app

  1. Refer to the Set Up a PhoneGap Environment Guide to get starterd.
  2. Add the Kinvey AngularJS library script tag to the generated www/index.html.
    <script src="//da189i1jfloii.cloudfront.net/js/kinvey-angular-sdk-3.5.2.min.js"></script>
  3. Refer to Configure Your App on how to get started using the Kinvey AngularJS library with your PhoneGap app.

How to use in an Ionic app

Note - Check out our starter app in the Ionic Marketplace or on GitHub.

  1. Follow the Ionic Getting Started Guide to setup your Ionic environment.
  2. Add the Kinvey AngularJS library script tag to the generated www/index.html.
    <script src="//da189i1jfloii.cloudfront.net/js/kinvey-angular-sdk-3.5.2.min.js"></script>
  3. Refer to Configure Your App on how to get started using the Kinvey AngularJS library with your Ionic app.

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.

Got a question?