The Reblaze SDK: Read me first
Documentation for version 1.9.2

Overview

Reblaze provides an SDK (available at https://bitbucket.org/reblaze/mobilesdk/) for use in mobile/native applications. Customers rebuild and publish their applications with the SDK embedded. The SDK currently supports:
Android:
    Java
iOS:
    Swift (Xcode 11)
    Objective-C (Xcode 11)
(A previous release also included React Native support. This will added again in a future release.)

Getting Started

First, read the platform-independent information on this page. Then go to the page for your specific platform (links are at the bottom of this page) and follow its instructions.

How the SDK works

Reblaze provides an SDK for use in mobile/native applications. Customers rebuild and publish their applications with the SDK embedded.
In the discussion below, customer will refer to the organization who uses the Reblaze SDK, client application will refer to the application in which the SDK is used, and user will refer to the end user of the client application.

Three modes

There are three possible modes in which to use the SDK. In increasing order of robustness, they are:
    Authentication Only
    Authentication and Basic Events
    Authentication and Custom Events
The mode is determined by the SDK methods that the client application calls from this list:
    configure()
    start()
    getHash()
    sendEvent()
Mode
configure()
start()
getHash()
sendEvent()
Authentication Only
Yes
No
Yes
No
Authentication and Basic Events
optional
Yes
Yes
No
Authentication and Custom Events
optional
Yes
Yes
Yes
The method names vary slightly by OS and language; code samples are provided in the OS-specific instructions. Also note that this discussion is only about the SDK mode; the list of methods above is not an exhaustive list of methods that the client application will call during its lifetime.
Each mode is described below.

Authentication Only mode

In this mode, the SDK provides basic client authentication. It signs the application, authenticates the device, and verifies user identity.
All communications occur over TLS and include an HMAC signature to harden communications between the application and the microservice/API endpoint. The signatures are non-reproducible, non-guessable, and non-repeating. They provide a reliable, secure mechanism to verify that the packets are originating from a legitimate app user, and not from an emulator or other bot.

Methods used for this mode:

    During initialization, the client application calls configure().
    The application may change configuration at any time, by calling configure() again.
    The application may shutdown the SDK by calling stop() . After shutdown, the SDK can be reinitialized by calling configure() again.
    Each time a request is sent upstream, the getHash() method will be called. This hash with its timestamp will be passed with other request headers. Detailed usage is discussed on the OS-specific pages.

Authentication and Basic Events mode

In this mode, the SDK provides client authentication, and also sends events to Reblaze. These are generated automatically by the user's interaction with the client application. (An internal thread accumulates events and sends them to Reblaze at an interval set at SDK activation).
The default events currently gathered by Reblaze are:
    for Android: click, gesture, keyDown, keyPress, keyUp, touchDown, touchMove, touchUp
    for iOS: click, deviceOrientation, gesture, keyDown, keyPress, keyUp, touchDown, touchMove, touchUp
Reblaze includes these events in its console. They can be observed by using this filter: url:/8d47.
Reblaze uses these events to build behavioral profiles for users of the client application. After an initial learning period, Reblaze will understand how legitimate users interact with the application. Subsequent users who do not conform to these behavioral patterns can be flagged as suspicious and/or blocked from access to the API endpoint.
This provides an additional layer of security, based on private analytics and cumulative user-event data to which threat actors have no access. Thus, it provides an additional form of client authentication that is extremely difficult for threat actors to defeat.

Methods used for this mode:

There are two possible approaches for this mode: one using configure() and start(), and the other using start() alone.
The first approach is provided for backwards compatibility with v1.8. If this is not needed, the second approach is simpler.
    Using configure() and start():
      To initialize the SDK, call configure() .
      After calling configure() for the first time, call start().
        When calling start(), all the parameters can be supplied.
        Or, the parameters <YOUR-USER-KEY-VALUE> and <YOUR-SECRET> can be omitted, since they are already supplied in the call to configure() .
      Each time a request is sent upstream, the getHash() method will be called. Detailed usage is discussed on the OS-specific pages.
    Using start() alone:
      To initialize the SDK, call start() .
      At the end of the application's lifetime, stop() should be called.
      Each time a request is sent upstream, the getHash() method will be called. Detailed usage is discussed on the OS-specific pages.

Authentication and Custom Events mode

In this mode, the SDK provides client authentication, sends default events to Reblaze, and also sends custom events generated by the client application. (The custom events are added to the same queue that the default events use.)
Each custom event is identified with a string chosen by the customer. Customers can define as many types of events as they wish.
Sending more types of events has the following benefits:
    Reblaze can construct more sophisticated behavioral profiles, and thus can enforce more robust security policies. Example: a mobile API endpoint is receiving numerous requests for data from a specific IP address. Those requests for data are usually generated by a user interacting with the customer's application in a certain way. If the customer has coded the application so that all these interactive events are sent to Reblaze, then Reblaze will have learned that these types of data requests should be accompanied by these specific custom events. A high number of data requests that are not accompanied by these event notifications would indicate that this is not a legitimate user; instead, it is probably an attacker using an emulator.
    Reblaze includes all the custom events in its traffic logs. Thus, customers can view fuller records of all the events being generated by each user.

Methods used for this mode:

    All the methods described above for Authentication and Basic Events mode:
      configure() (which is optional, as described above)
      start()
      stop()
      getHash().
    sendEvent() will be used to send the custom events. Detailed usage is discussed on the OS-specific pages.

Start Method arguments

The SDK methods use a variety of arguments. For example, depending on OS and language, the start() method looks like this:
1
reblaze.start(
2
"<YOUR-BACKEND-SERVICE-URL>",
3
"<YOUR-SECRET>",
4
"<YOUR-USER-KEY-NAME>",
5
"<YOUR-USER-KEY-VALUE>",
6
<SHOULD-SHOW-LOGS>,
7
<TRANSMISSION-INTERVAL>,
8
<REPORT-LOCATION>,
9
"<USER-AGENT>");
Copied!
The names above are placeholders. In your code, they should be replaced by actual values.
For example:
1
reblaze.start(
2
"https://api.example.com",
3
"abcde09876",
4
"UserName",
6
true,
7
30,
8
false,
9
"myMobileApp-version1.4.017");
Copied!
Here are the arguments used in the various methods.
Argument
Description
YOUR-BACKEND-SERVICE-URL
URL for the customer's application server.
YOUR-SECRET
Secret value issued to the customer by Reblaze. (Starting with Reblaze version 2.14, this can be edited by the customer in the Web Proxy section of the UI.)
YOUR-USER-KEY-NAME
The name of a field that contains a unique value for this user. (Example: UserName.)
YOUR-USER-KEY-VALUE
The value for the field specified above. (For example, the user's email address.)
SHOULD-SHOW-LOGS
Boolean value specifying whether logs should be printed in the debug console.
TRANSMISSION-INTERVAL
The interval in seconds for how often events are sent to the customer's application server.
Minimum interval: 12 (i.e, five transmissions per minute). Maximum interval: 300 (one transmission every five minutes).
A value of -1 disables the event transmission mechanism.
Other values: an error message is logged and an exception is raised.
REPORT-LOCATION
A boolean which tells Reblaze whether or not the user's location will be accessed and reported.
USER-AGENT
A string to be used for reports and events. This is a custom string, to be used at your discretion. It is an optional argument: if it is not provided, a default value will be used.
Reblaze uses the first two arguments to identify the application. Reblaze protects the customer's API endpoint(s) using the security rulesets defined for this application, and also based on the behavioral data accumulated for all users of this application.
The third and fourth arguments identify the individual end user. Reblaze uses this to enforce per-user security rulesets such as dynamic rate limits. These arguments also allow you to observe the activities of individual users within the traffic logs.

Offline Testing

To perform offline tests, use a URL that begins with mock: instead of https:. The SDK will not try to use the network, but will pretend to be sending events to Reblaze and receiving acknowledge from the server.

How to use the SDK on your platform

Follow these instructions for your specific platform:
Last modified 11mo ago