Android SDK

This section shows you how to include datalinker in an existing Android app. We assume that you have setup a SENDER service called com.myorg.sender and a document type called com.myorg.my-document-type.

AD_HOC and RECEIVER_INITIATED_RECEIVER services can be configured by user by scanning a QR code. This QR code contains the session ID to send the data to as well as an AES key and an initialization vector (in case of AD_HOC services) and a fingerprint (in case of RECEIVER_INITIATED_RECEIVER services). The datalinker UI handles the scanning of the QR code and the encryption for you. Refer to the Overview to implement this behavior yourself.

The datalinker Android SDK is split into three modules:

  • datalinker-core: This is the core module for sending data.
  • datalinker-ui: This module contains the datalinker UI for the users of your app.
  • datalinker-analytics: This module simplifies the use of datalinker analytics to track user behavior.

Setting up Dependencies

  1. Add jcenter-repository:
repositories {
  google()
  jcenter()
}
  1. Add the following dependencies:
dependencies {
    implementation "io.datalinker.api:core:1.0.0"
    implementation "io.datalinker.ui:1.0.0"
    implementation "io.datalinker.api:analytics:1.0.0"
}

The first dependency is not necessary as it is required by the second and the third library.

  1. Sync Your Project

Register your app as a client for your service

In your Application class, add the following statement to configure your app to use datalinker:

@Override
public void onCreate() {
    super.onCreate();

    Datalinker.configureService("com.myorg.sender");
}

This sets up your project to connect to your SENDER service. Each instance of your app will then create a new client of this service using an auto-generated password.

Adding receiver services

RECEIVER_INITIATED_RECEIVER services can be added either through the datalinker UI or programmatically. SENDER_INITIATED_RECEIVERS can only be added programatically.

Note

Use either the datalinker UI or a custom UI to add RECEIVER_INITIATED_RECEIVER services. It is not allowed to mix both ways in the same app.

Note

When adding SENDER_INITIATED_RECEIVERS, they will still be visible in the datalinker UI. However, they can only be paused and not be removed by the user. Don’t try to remove them in your code but instead deactivate them.

To add a receiver service, simply pass the service ID and a flag, to indicate if the service should be enabled by default:

Datalinker.addService("com.myorg.receiver-initiated", true);

Both receiver types can either be active or inactive. Data will only be sent to active services.

Using the datalinker UI

The datalinker UI makes managing services for your users a breeze. You can launch the LinkerServiceActivity with Your current context:

if (Datalinker.isReady()) {
    DatalinkerUi.presentShareView(this);
}

using Kotlin an extension function on Datalinker is available:

if(Datalinker.isReady()) {
    Datalinker.presentShareView(this)
}

Note

Use the isReady() method to ensure that datalinker has finished configuring itself. If you show the UI before datalinker has logged your user in, it will not show the available services.

Sending data

Once you configured some services, you can send new data to all of them:

final JsonObject data = new JsonObject();
data.addProperty("timestamp", new Date().getTime());
data.addProperty("number", Math.random() * 100);
Datalinker.sendDataToReceivers(data, "com.myorg.my-document-type");

To send data only to a specific service, you can pass the receiver service as an argument:

final JsonObject data = new JsonObject();
data.addProperty("timestamp", new Date().getTime());
data.addProperty("number", Math.random() * 100);
Datalinker.sendData("com.myorg.receiver-service", data, "com.myorg.my-document-type");

Both methods work with both RECEIVER_INITIATED_RECEIVER and SENDER_INITIATED_RECEIVER services.

Optionally, you can add unencrypted parameters to you data:

final JsonObject data = new JsonObject();
data.addProperty("timestamp", new Date().getTime());
data.addProperty("number", Math.random() * 100);

final JsonObject parameters = new JsonObject();
parameters.addProperty("foo", "bar");

Datalinker.sendDataToReceivers(data, "com.myorg.my-document-type", parameters);
Datalinker.sendData("com.myorg.receiver-service", data, "com.myorg.my-document-type", parameters);

Note

datalinker will start sending data the next time your app launches. It will preserve the correct order of the data.

Using AD_HOC services

AD_HOC services receive data once. To support these kind of services, your app has to register as a datalinker datasource. When a user scans a QR code for an AD_HOC service, your app will be asked to provide the relevant data.

To register as a datasource for datalinker, implement the DatalinkerDataSource interface and set it as the datasource:

Datalinker.setDataSource(datasource);

The datasource will need to implement methods for returning the number of documents to send, the document type ID of these documents and the actual data for each of this documents. The following example returns three documents for displaying random values with their associated timestamp.

final DatalinkerDataSource dataSource = new DatalinkerDataSource() {

        @Override
        public int numberOfDocuments(@NotNull final String serviceId) {
            return 3;
        }

        @NotNull
        @Override
        public String documentTypeIdForDocumentAtIndex(@NotNull final String serviceId, final int index) {
            switch (index) {
                case 0:
                    return "com.myorg.random-number-bar-chart";
                case 1:
                    return "com.myorg.random-number-line-chart";
                case 2:
                    return "com.myorg.random-number-table";
                default:
                    return "";
            }
        }

        @NotNull
        @Override
        public String documentAtIndex(@NotNull final String serviceId, final int index) {
            final JsonArray result = new JsonArray();

            final Event[] events = this.viewModel.getEvents();

            switch (index) {
                case 0:
                case 1:
                    final JsonArray leftAxix = new JsonArray();
                    final JsonArray rightAxix = new JsonArray();

                    for (final Event event : events) {

                        final JsonArray leftAxixValue = new JsonArray();
                        leftAxixValue.add(event.getTimestamp().getTime() * 1000);
                        leftAxixValue.add(event.getValue());
                        leftAxix.add(leftAxixValue);

                        final JsonArray rightAxixValue = new JsonArray();
                        rightAxixValue.add(event.getTimestamp().getTime() * 1000);
                        rightAxixValue.add(Math.pow(event.getValue(), 2));
                        rightAxix.add(rightAxixValue);
                    }

                    result.add(leftAxix);
                    result.add(rightAxix);
                    break;
                case 2:
                    for (int i = 0; i < events.length; i++) {
                        final JsonArray row = new JsonArray();
                        final JsonArray value = new JsonArray();
                        value.add(events[i].getTimestamp().getTime() * 1000);
                        value.add(events[i].getValue());

                        row.add(i);
                        row.add(value);

                        result.add(row);
                    }
            }
            return result.toString();
        }
    };

Using datalinker analytics

datalinker analytics is a SENDER_INITIATED_SERVICE for collecting user behavior inside your app. While very simple, it will provide you with raw data to give you full control. Data sent to datalinker analytics will be decrypted on the server and thus may not contain any personal or sensitive data. In particular, it is not premitted to send any user-identifiable information to datalinker analytics.

To start a new session, e. g. when launching the app, call the startSession() on Application launch:

@Override
public void onCreate() {
    super.onCreate();

    Datalinker.configureService("com.myorg.sender");
    DatalinkerAnalytics.startSession();
}

To send data to datalinker analytics, simply call its sendEvent() function:

DatalinkerAnalytics.sendEvent("Added a new random number.");

Again, you may add some parameters to this data:

final JsonObject parameters = new JsonObject();
parameters.addProperty("foo", "bar");

DatalinkerAnalytics.sendEvent("Added a new random number.", parameters);

Resetting datalinker

Attention

datalinker’s reset() function may not be used in production environments. It is simply used to reset all configuration during development.

The datalinker SDK stores the assigned client ID and the generated password in your user’s keychain. In addition, it stores the configuration of all services as well as the data to send in the file system. To reset all of this information during development, call the reset() function.

Datalinker.reset();