Getting Started

If you are starting with a fresh Xamarin project or an existing app, follow these steps to add the Kinvey Xamarin library to your app and set up the Kinvey Client.

Prerequisites

You might need to set the "iOS Build Linker Behavior" option to "Don't Link" or "Link Framework SDKs Only"

Project Set Up

Using Xamarin Studio

The library is distributed as a PCL through nuget.

iOS

Right click your project -> Add -> Add Packages -> Kinvey-ios

Android

Right click your project -> Add -> Add Packages -> Kinvey-Android

Cross-platform (PCL)

Right click your project -> Add -> Add Packages -> Kinvey

In addition, the library is also available as a component from the Xamarin Component Store.

iOS, Android and PCL

Right click on the Component folder in your project -> Get More Components...

This will launch a Xamarin Components dialog. From here, use the Search Components edit box to search for Kinvey. Click on the result, which will open up the Kinvey SDK page. From here, click the Add to App button.

Using SDK Source Code

The Kinvey Xamarin SDK is 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.

Add an App Backend

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

In the Kinvey console, click "Create an App" and enter the name of your app when prompted.

Add an app in Console

You can find your key and secret in the dropdown menu in the environment sidebar.

Key and secret

Copy the key and secret when performing the next steps.

Initialize a Client

The Client.Builder is used to build and initialize the Client before making any calls to the Kinvey API.

You need to set the following arguments on your client:

  • Set your App Key and App Secret obtained from the Kinvey console.
  • Set a Logger delegate, so the Library can write output.
  • Set a file path and SQLite implementation for persisting data.

Initializing a Client is usually done when your application first starts.

iOS Client Creation

using Kinvey;
...

Client.Builder builder = new Client.Builder(your_app_key, your_app_secret)
            .setLogger(delegate(string msg) { Console.WriteLine(msg); })
            .setFilePath(NSFileManager.DefaultManager.GetUrls (NSSearchPathDirectory.DocumentDirectory, NSSearchPathDomain.User) [0].ToString())
            .setOfflinePlatform(new SQLitePlatformIOS());

Client kinveyClient = builder.Build();

Android Client Creation

using Kinvey;
...

Client.Builder builder = new Client.Builder(your_app_key, your_app_secret)
            .setLogger(delegate(string msg) { Console.WriteLine(msg); })
            .setFilePath(System.Environment.GetFolderPath(System.Environment.SpecialFolder.Personal))
            .setOfflinePlatform(new SQLitePlatformAndroid());

Client kinveyClient = builder.Build();

For Android 7 and later, use SQLitePlatformAndroidN() instead of SQLitePlatoformAndroid() when setting the offline platform. Also, be sure to add a reference to Mono.Data.Sqlite in your project.

PCL Client Creation

using Kinvey;
...

Client.Builder builder = new Client.Builder(your_app_key, your_app_secret)
            .setLogger(delegate(string msg) { Console.WriteLine(msg); })
            .setFilePath(filePath)
            .setOfflinePlatform(new SQLite.Net.Platform.Generic.SQLitePlatformGeneric())

Client kinveyClient = builder.Build();

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

Client.Builder builder = new Client.Builder(your_app_key, your_app_secret).setBaseURL("<your dedicated host URL>");

final Client kinveyClient = builder.Build();

Xamarin.Forms Client Creation

Xamarin.Forms offers you the ability to build UIs for your Xamarin apps that target both iOS and Android devices using a common codebase. However, you still need to define some platform-specific behavior when working with the Kinvey SDK, specifically for offline database support. In the next examples, this is achieved using the Xamarin.Forms Dependency Service.

Common Code

To initialize your Xamarin.Forms client, first add the following common interface. Place the code in the same shared code section of your project from where you will initialize the Kinvey client.

public interface ISQLite
{
    SQLite.Net.Interop.ISQLitePlatform GetConnection();
    string GetPath();
}

Next, in each of the iOS and Droid parts of your project, add a new class that implements the ISQLite interface that you defined above. An example for each is provided below, but note that the inheritance of the ISQLite interface must use the actual namespace of your project. Substitute it for the KXStarterApp example namespace.

iOS

Adapt the following code to your project to address iOS devices.

using Xamarin.Forms;
using SQLite.Net.Platform.XamarinIOS;
using Foundation;

[assembly: Dependency(typeof(SQLite_iOS))]
// ...
public class SQLite_iOS : KXStarterApp.ISQLite
{
    public SQLite_iOS() { }
    public SQLite.Net.Interop.ISQLitePlatform GetConnection()
    {
        return new SQLitePlatformIOS();
    }

    public string GetPath()
    {
        return NSFileManager
            .DefaultManager
            .GetUrls(NSSearchPathDirectory.DocumentDirectory, NSSearchPathDomain.User)[0]
            .ToString();
    }
}

Android

Adapt the following code to your project to address Android devices.

using Xamarin.Forms;
using SQLite.Net.Platform.XamarinAndroid;

[assembly: Dependency(typeof(SQLite_Android))]
// ...
public class SQLite_Android : KXStarterApp.ISQLite
{
    public SQLite_Android() { }
    public SQLite.Net.Interop.ISQLitePlatform GetConnection()
    {
        return new SQLitePlatformAndroid();
    }

    public string GetPath()
    {
        return System.Environment.GetFolderPath(System.Environment.SpecialFolder.Personal);
    }
}

Initialize the Client for Xamarin.Forms

Finally, after the platform-specific functionality has been properly set up to use Dependency Service, you can initialize the client:

using Kinvey;
...
Client.Builder builder = new Client.Builder(your_app_key, your_app_secret)
            .setFilePath(DependencyService.Get<ISQLite>().GetPath())
            .setOfflinePlatform(DependencyService.Get<ISQLite>().GetConnection());

Client kinveyClient = builder.Build();

Verify Set Up

You can use the PingAsync() method on the kinveyClient object to verify that the app has valid credentials.

try
{
    PingResponse response = await kinveyClient.PingAsync();
}
catch (Exception e)
{
    // an error has occured
}

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?