Mobile Applications

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:

import Castle

// Place the below in your UIApplicationDelegate application:didFinishLaunchingWithOptions:
Castle.configure(withPublishableKey: "{Publishable-API-Key}")
#import <Castle/Castle.h>

// Place the below in your UIApplicationDelegate application:didFinishLaunchingWithOptions:
[Castle configureWithPublishableKey: @"{Publishable-API-Key}"];
import io.castle.android.Castle;

// Place the below in your Application class onCreate method
Castle.configure(application, "{Publishable-API-Key}");

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");

If secure mode is enabled make sure to call secure before identify or any other tracking calls (track, screen) since any events not containing the user_signature will be discarded.

Step 4. Tracking screen views

Screen

The screen call lets you record whenever a user sees a screen. It could look something like this:

// Track a screen view
Castle.screen("Menu")

// OR

// Track screen view and include some properties
Castle.screen("Menu", properties: ["locale": "en_US"])
// Track a screen view
[Castle screen:@"Menu"];

// OR

// Track a screen view and include some properties
[Castle screen:@"Menu" properties:@{ @"locale": @"en_US" }];
// Track a screen view
Castle.screen("Menu");

// OR

// Track a screen view and include some properties
Map<String, String> properties = new HashMap<String, String>() {{
    put("locale", "en_US");
}};
Castle.track("Menu", properties);

Step 5. Securing requests from Mobile SDKs

Secure Mode is available in Castle iOS SDK v1.0+ and Android SDK v1.0.3+

Securing requests is optional, but recommended. We strongly encourage all Castle customers to enable Secure Mode to prevent fraudsters from impersonating your users. This is important to make sure fraudsters can't lock out your users by feeding in bad behavior. Read more about Secure mode in the "Secure Requests" section of the documentation.

If Secure Mode is enabled on your Castle environment, you will need to pass the user signature to the mobile SDK using the secure method:

Castle.secure("944d7d6c5187cafac297785bbf6de0136a2e10f31788e92b2822f5cfd407fa52")
[Castle secure:@"944d7d6c5187cafac297785bbf6de0136a2e10f31788e92b2822f5cfd407fa52"];
Castle.secure("944d7d6c5187cafac297785bbf6de0136a2e10f31788e92b2822f5cfd407fa52");

Once enabled the user signature will be included in every event. The user_signature will be persisted locally. Calling reset will remove the stored user signature and calling secure again will replace the old user signature. Once secure mode is enabled any events not containing the user_signature field will be discarded.

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 20 events. This ensures that the device fingerprint is fully profiled before any requests to your server side.

Automatic screen tracking

When automatic screen tracking is enabled any activities or view controllers shown will automatically generate a screen event. The screen name will use a normalized version of the activities or view controllers title. For more granular control we suggest disabling automatic screen tracking (on by default) and calling screen manually.

Configuration

The SDK allows for some configurable behaviour, below is an example on how configuration is done.

// Create configuration
let configuration = CastleConfiguration(publishableKey: "{Publishable-API-Key}")
configuration.isScreenTrackingEnabled = true // Default true
configuration.isDebugLoggingEnabled = true // Default false
configuration.isDeviceIDAutoForwardingEnabled = true // Default false
configuration.flushLimit = 10; // Default 20
configuration.maxQueueLimit(100); // Default 1000
configuration.baseURLWhiteList = [ URL(string: "https://api.castle.io/")! ]

// Setup Castle SDK with provided configuration
Castle.setup(with: configuration)
NSArray *baseURLWhiteList = @[ [NSURL URLWithString:@"https://api.example.com/"] ];

// Create configuration
CastleConfiguration *configuration = [CastleConfiguration configurationWithPublishableKey:@"{Publishable-API-Key}"];
configuration.screenTrackingEnabled = YES; // Default YES
configuration.debugLoggingEnabled = YES; // Default NO
configuration.deviceIDAutoForwardingEnabled = YES; // Default NO
configuration.flushLimit = 10; // Default 20
configuration.maxQueueLimit = 100; // Default 1000
configuration.baseURLWhiteList = baseURLWhiteList;

// Setup Castle SDK with provided configuration
[Castle configure:configuration];
ArrayList<String> baseUrlWhiteList = new ArrayList<>();
baseUrlWhiteList.add("https://api.example.com/");

CastleConfiguration configuration = new CastleConfiguration.Builder()
    .publishableKey("{Publishable-API-Key}")
    .screenTrackingEnabled(true) // Default true
   .debugLoggingEnabled(true) // Default false
   .flushLimit(10) // Default 20
    .baseURLWhiteList(baseUrlWhiteList)
    .maxQueueLimit(100) // Default 1000
    .build();

// Setup Castle SDK with provided configuration
Castle.configure(application, configuration);