Mobile Integration Guide

The Castle mobile SDKs automatically capture device information and user interactions analog to Castle.js. Start by installing and configuring the mobile SDK:

Step 1. Configuration

Fetch your Publishable Key from the Castle Dashboard and configure the SDK:

// Place the below in your app's application:didFinishLaunchingWithOptions:
import Castle

Castle.configure(withPublishableKey: "pk_sBwv6ZkCEsEzRqqFcBj8wZ")
// Place the below in your app's application:didFinishLaunchingWithOptions:
#import <Castle/Castle.h>

[Castle configureWithPublishableKey: @"pk_sBwv6ZkCEsEzRqqFcBj8wZ"];
// Place the below in your app's onCreate
import io.castle.android.Castle;

// `application` is an `android.app.Application` object
Castle.configure(application, "pk_btApAXqt1jpJtEARf1stsnvyov6czPmn");

Step 2. Forward the Client ID along with API requests

By forwarding a client identifier, the Client ID, from the mobile client to the server-side, activity from the two sources can be linked together to form a strong protection against attacks where this link is not present, for example when an attacker is attacking your API directly without going through the mobile client.

You will need to forward the client identifier as a request header to every request to your API. This header will then automatically be parsed by the Castle server-side SDK:

// NSURLRequest and ASIHTTPRequest
request.setValue(
  Castle.clientId(),
  forHTTPHeaderField: CastleClientIdHeaderName
)

// CFNetwork
CFHTTPMessageSetHeaderFieldValue(
  request,
  CastleClientIdHeaderName,
  Castle.clientId()
);
// NSURLRequest and ASIHTTPRequest
[request setValue:[Castle clientId]
         forHTTPHeaderField:CastleClientIdHeaderName];

// CFNetwork
CFHTTPMessageSetHeaderFieldValue(
  request,
  CastleClientIdHeaderName,
  [Castle clientId]
)
// OkHttp
requestBuilder.header(
    Castle.clientIdHeaderName,
    Castle.clientId();
);

// HttpURLConnection
httpUrlConnection.setRequestProperty(
    Castle.clientIdHeaderName,
    Castle.clientId();
);

// Volley
headers.put(
    Castle.clientIdHeaderName,
    Castle.clientId();
);

Step 3. Identify logged in users

The identify call lets you tie a user to their action and should be called right after the user logged in successfully. The user_id will be persisted locally so subsequent activity will automatically be tied to that user.

Castle.identify("e325bcdd10ac")
[Castle identify:@"e325bcdd10ac"];
Castle.identify("e325bcdd10ac");

Topics

Queue flushing

The SDK queues API calls to save battery life, and it only flushes queued events to the Castle API whenever the app is installed, updated, opened or closed; when identify is called; or when the queue reaches 10 events. This ensures that the device fingerprint is fully profiled before any requests to your server side.