Sign In

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:


Configuration

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

1
2
3
4
	import Castle

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

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
	// NSURLRequest and ASIHTTPRequest
	request.setValue(
	  Castle.clientId(),
	  forHTTPHeaderField: CastleClientIdHeaderName
	)

	// CFNetwork
	CFHTTPMessageSetHeaderFieldValue(
	  request,
	  CastleClientIdHeaderName,
	  Castle.clientId()
	);

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.

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


Tracking screen views

Screen

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

1
2
3
4
5
6
7
	// Track a screen view
	Castle.screen("Menu")

	// OR

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

Securing requests from Mobile SDKs

Secure Mode is available in Castle iOS SDK v1.0.0+ and Android SDK v1.1.0+

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.

Since the secure mode signature is generated on your backend you will need to pass it to your application. A straight forward way of doing that is by including the signature in the authentication response. After receiving the authentication response the application can set the signature by calling the secure method.

The secure mode signature is a SHA-256 HMAC in hex format where the shared secret is your API Secret, and the value is the User ID being tracked in identify.

See the example below on how the signature can be generated on your backend.

1
2
		OpenSSL::HMAC.hexdigest("sha256", "YOUR_API_SECRET", "1234");
	
You will need to set the secure mode signature before calling identify, otherwise the identify event will be rejected by the API since it won’t include the secure mode signature.

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:

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
	// 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)