Getting Started

This document outlines the steps to initialize the ZumoKit SDK on Android, iOS and React Native.

Initialization

You'll need the following credentials to get started:

  • txServiceUrl - This is the Transaction Service WebSocket URL
  • apiKey - A unique key used to interact with the API provided by your account manager.
  • apiRoot - This is the root URL of ZumoKit API.
  • myRoot - This is the base URL of your API on which ZumoKit bundle library is configured.

Credentials are environment specific and are different for sandbox and production environments.

ZumoKit SDK assumes that ZumoKit bundle authentication endpoint is accessible at myRoot/wallet/preauth. For example if your base URL is https://www.example.com/ and ZumoKit Bundle is accessible at https://www.example.com/wallet/preauth, then myRoot is https://www.example.com/.

The entry point for interaction with ZumoKit SDK is ZumoKit instance.

You'll need to create a new instance of the class and save a reference to it for use later on Android/iOS. Unlike Android an iOS implementations, a reference doesn't need to be stored in React Native SDK.

import money.zumo.zumokit.ZumoKit;

...

String myRoot = "https://www.example.com/";

// Initialize ZumoKit
ZumoKit zumoKit = new ZumoKit(TX_SERVICE_URL, API_KEY, API_ROOT, myRoot);
#import <ZumoKit/ZumoKit.h>

...

NSString *myRoot = @"https://www.example.com/";

// Initialize ZumoKit
ZumoKit *zumoKit = [[ZumoKit alloc] initWithTxServiceUrl:TX_SERVICE_URL
                                               apiKey:API_KEY
                                              apiRoot:API_ROOT
                                               myRoot:myRoot
];
import ZumoKit from 'react-native-zumo-kit';

...

ZumoKit.init({
        txServiceUrl: TX_SERVICE_URL,
        apiKey: API_KEY
        apiRoot: API_ROOT,
        myRoot: 'https://www.example.com/',
    });

You can check the SDK version that you are currently using by accessing static version attribute:

Log.i("ZUMOKIT_VERSION", ZumoKit.getVersion());
NSLog(@"ZUMOKIT_VERSION: %@", [ZumoKit version]);
console.log(ZumoKit.VERSION);

Authentication

Once you've initialised ZumoKit within your application, you'll need to authenticate a user to start using the SDK.

ZumoKit assumes your platform uses JWT tokens to authenticate your users. When calling SDK’s auth method make sure the JWT token for the current user is passed to the method. To get started follow these steps:

  1. Register/populate your API's data storage with user accounts.
  2. Login into your API using a user account.
  3. Pass the user's JWT token to ZumoKit SDK's authentication method.
  4. If authentication is successful you can continue with wallet creation and other SDK related operations.

In the following example we provide authenticated user's JWT token to the auth method on the ZumoKit instance we created in the Initialization section. If your API requires any additional headers for authenticated request, for instance some kind of API key, you can propagate these via headers parameter of auth method.

In case authentication succeeded user object will be returned. In case of error, error details will be provided. Check Handling Errors section of these guides for more information on handling errors.

HashMap<String, String> optionalHeaders = new HashMap<String, String>();
optionalHeaders.put("Optional-Header-1", "example-value");

this.zumoKit.auth(USER_TOKEN, optionalHeaders, new AuthCallback() {
    @Override
    public void onError(Exception e) {
        // Something went wrong authenticating.
        String errorType = ((ZumoKitException) e).getErrorType();
        String errorCode = ((ZumoKitException) e).getErrorCode();
        String errorMessage = e.getMessage();
    }

    @Override
    public void onSuccess(User user) {
        // Authentication was successful!
    }
});
NSDictionary *optionalHeaders = @{ @"Optional-Header-1" : @"example-value"};

[zumoKit auth:USER_TOKEN
      headers: optionalHeaders
   completion: ^(ZKUser * _Nullable user, NSError * _Nullable error){

    if (error != nil) {
        // Something went wrong authenticating.
        NSLog(@"Error Type: %@", error.userInfo[ZKZumoKitErrorTypeKey]);
        NSLog(@"Error Code: %@", error.userInfo[ZKZumoKitErrorCodeKey]);
        NSLog(@"Error Message: %@", error.localizedDescription);
        return;
    }

     // Authentication was successful!
}];
try {
    const user = await ZumoKit.auth(USER_TOKEN, {
        "Optional-Header-1": "example-value"
    });
    // Authentication was successful!
} catch (error) {
    // There was a problem authenticating.
    { type, code, message } = error;
}

As all methods in ZumoKit React Native SDK use promises, we can take advantage of ES6's async/await syntax. An exception is thrown if the promise is rejected and the error can be caught and handled.

Environments

Sandbox

The sandbox environment is used for testing and validating integrations prior to deploying to production.

TX_SERVICE_URL: wss://tx.sandbox.zumo.money/
API_ROOT: https://kit.sandbox.zumo.money/

ZumoKit on sandbox environment interacts with Bitcoin Testnet network meaning that all Bitcoins (BTC) are test Bitcoins. You can get test Bitcoins (BTC) here and you can check transactions on BlockCypher.

Similary, sandbox environment uses Ethereum Rinkeby test network meaning that all Ethers (ETH) are Rinkeby test Ethers. You can get test Ethers (ETH) here and you can check transactions on Rinkeby Etherscan.

Production

The production environment is used for production applications.

TX_SERVICE_URL: wss://tx.zumo.money/
API_ROOT: https://kit.zumo.money/
← React NativeManage User Wallet →