ironSource.atom SDK for Android

Atom-Android is the official ironSource.atom SDK for the Android platform! Follow the steps below to integrate this SDK in your project:

Step 1. Install the SDK
Step 2. Send Events

Before You Start
Make sure to complete the account setup for Atom before you integrate the SDK. You can follow our guidelines to set up your account here.

Step 1. Install the SDK

Atom supports two installation methods to integrate the Android SDK for Atom; namely Gradle and Maven. We recommend using the Gradle method.

Installation for Gradle Project

Add the following repository to your build.gradle configuration file; located in your project’s module level:

repositories {
   maven { url "https://raw.github.com/ironSource/atom-android/mvn-repo/" }
}Light theme
Dark theme
Copy to clipboard

Next, add this dependency for the Atom SDK:

dependencies {
   compile 'io.ironsourceatom.sdk:atom-sdk:1.1.0'
}Light theme
Dark theme
Copy to clipboard

Installation for Maven Project

Add the following repository to your pom.xml:

<repositories>
    <repository>
        <id>atom-java</id>
        <url>https://raw.github.com/ironSource/atom-android/mvn-repo/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
    </repository>
</repositories>Light theme
Dark theme
Copy to clipboard

Next, add this dependency for the Atom SDK:

<dependencies>
    <dependency>
        <groupId>io.ironsourceatom.sdk</groupId>
        <artifactId>atom-sdk</artifactId>
        <version>1.1.0</version>
    </dependency>
</dependencies>Light theme
Dark theme
Copy to clipboard

Step 2. Send Events

The Atom SDK for Android is divided into 2 separate services:

High Level Tracker
This tracker contains a local SQLite database and tracks events based on default parameters. You can also modify the below parameters as you see fit. You can use track() method in order to track the events to an Atom Stream. The tracker accumulates events and flushes them when it meets one or more of the following conditions :

Parameter Name	Type	Attributes	Description	Default
Flush Interval	Number	Optional	Event Sending Interval	10 seconds
Bulk Length	Number	Optional	Number of Records in Each Bulk Request	4 events
Maximum Request Limit	Number	Optional	Size of Request in Bytes	1 MB

Note: Note: In case of failure the tracker will perform an exponential back-off with jitter. The tracker stores events in a local SQLITE database.

Tracker usage

Add the following lines to your AndroidManifest.xml:

<service android:name="io.ironsourceatom.sdk.ReportService" />Light theme
Dark theme
Copy to clipboard

Next, add ironSource Atom to your main activity as follows:

import io.ironsourceatom.sdk.IronSourceAtomFactory;
import io.ironsourceatom.sdk.IronSourceAtomTracker;
public class BaseMainActivity extends Activity {
    private IronSourceAtomFactory ironSourceAtomFactory;
    private static final String TAG = "SDK_EXAMPLE";
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main_v2);
        // Create and config IronSourceAtomFactory instance
        ironSourceAtomFactory = IronSourceAtomFactory.getInstance(this);
        ironSourceAtomFactory.enableErrorReporting();
        ironSourceAtomFactory.setBulkSize(5);
        ironSourceAtomFactory.setFlushInterval(3000);
        ironSourceAtomFactory.setAllowedNetworkTypes(IronSourceAtomFactory.NETWORK_MOBILE | IronSourceAtomFactory.NETWORK_WIFI);
        ironSourceAtomFactory.setAllowedOverRoaming(true);
    }
    public void sendReport(View v) {
        int id = v.getId();
        String stream = "your.atom.stream";
        // Atom tracking url
        String url = "http://track.atom-data.io";
        String bulkURL = "http://track.atom-data.io/bulk";
        String authKey = ""; // Pre-shared HMAC auth key
        // Configure tracker
        IronSourceAtomTracker tracker = ironSourceAtomFactory.newTracker(authKey);
        tracker.setISAEndPoint(url);
        tracker.setISABulkEndPoint(bulkURL);
        // Android Tracker Example
        JSONObject params = new JSONObject();
        try {
            params.put("event_name", "ANDROID_TRACKER");
            params.put("id", "" + (int) (100 * Math.random()));
        } catch (JSONException e) {
            Log.d(TAG, "Failed to track your json");
        }
        Log.d("[Tracking event]", params.toString());
        tracker.track(stream, params);
        // Will send this event immediately
        try {
            params.put("event_name", "ANDROID_TRACKER_SEND_NOW");
            params.put("id", "" + (int) (100 * Math.random()));
        } catch (JSONException e) {
            Log.d(TAG, "Failed to track your json");
        }
        Log.d("[TRACKER_SEND_NOW]", params.toString());
        tracker.track(stream, params, true);
        Log.d("[TRACKER_FLUSH]", "FLUSHING TRACKED EVENTS");
        tracker.flush();
    }
}Light theme
Dark theme
Copy to clipboard

Low Level API
This API contains 2 methods; once you call one of these methods, you will send the event to Atom:
1. putEvent() in order to send one event
2. putEvents()to send a batch of events

Low Level API Usage
This methods performs an HTTP post to Atom.
Add the following lines to your AndroidManifest.xml:

<service android:name="io.ironsourceatom.sdk.SimpleReportService" />
Light theme
Dark theme
Copy to clipboard

Next, add ironSource.Atom to your main activity as follows:

import io.ironsourceatom.sdk.IronSourceAtomFactory;
import io.ironsourceatom.sdk.IronSourceAtom;
public class BaseMainActivity extends Activity {
    private IronSourceAtomFactory ironSourceAtomFactory;
    private static final String TAG = "SDK_EXAMPLE";
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main_v2);
        // Create and config IronSourceAtomFactory instance
        ironSourceAtomFactory = IronSourceAtomFactory.getInstance(this);
        ironSourceAtomFactory.enableErrorReporting();
        ironSourceAtomFactory.setAllowedNetworkTypes(IronSourceAtomFactory.NETWORK_MOBILE | IronSourceAtomFactory.NETWORK_WIFI);
        ironSourceAtomFactory.setAllowedOverRoaming(true);
    }
    public void sendReport(View v) {
        String stream = "your.stream.name";
        // Atom tracking url
        String url = "http://track.atom-data.io";
        String authKey = ""; // Pre-shared HMAC auth key
        // Configure sender to use methods putEvent() or putEvents()
        IronSourceAtom atom = ironSourceAtomFactory.newAtom(authKey); // SET AUTH KEY HERE
        atom.setEndPoint(url);
        JSONObject params = new JSONObject();
        try {
            params.put("event_name", "ANDROID_PUT_EVENT");
            params.put("id", "" + (int) (100 * Math.random()));
        } catch (JSONException e) {
            Log.d(TAG, "Failed to track your json");
        }
        Log.d("[putEvent]", params.toString());
        atom.putEvent(stream, params.toString());
        Gson gson = new Gson(); // Used for Array to json conversion.
        List<ExampleData> bulkList = new ArrayList<>();
        for (int i = 0; i < 10; i++) {
            bulkList.add(new ExampleData((int) (Math.random() * 100), "ANDROID_PUT_EVENTS"));
        }
        Log.d("[putEvents]", gson.toJson(bulkList));
        atom.putEvents(stream, gson.toJson(bulkList));
    }
}Light theme
Dark theme
Copy to clipboard

Please refer to this document for more detailed information on every method and its correct usage.

Implementation Example

See our example section that illustrates how to send data to Atom:

For more information on the ironSource.Atom SDK for Android, visit our dedicated github page.