Getting started on Android

This page explains how to install the Equativ Display SDK into an Android application. This is the first step to complete before delivering ads in your application.

Prerequisites
Google Advertising ID & Transient ID
Installation
Location
Network Security Configuration

Prerequisites

There are some prerequisites prior to integrating the Equativ Display SDK in your application:

Android Studio.
Android 6 (API level 23) or higher.

Google Advertising ID & Transient ID

The Equativ Display SDK uses the Google Advertising ID of the device, which will be sent during ad calls. You should always comply with your local laws, check the Privacy laws compliancy page for more details.

The Google Advertising ID might be unavailable on some devices, either because the user has opted-out in the device settings or because the device does not implement the Google Play Services.

Installation

To import the Equativ Display SDK into your Android project, here are the steps to follow:

In the main build.gradle of your project, you must declare the repository where the Equativ Display SDK is hosted:

allprojects {
 repositories {
     google()

     // add the Equativ repository
     maven { url 'https://packagecloud.io/smartadserver/android/maven2' }

     // …
 }
}

In the dependencies section of your application module build.gradle file, declare the Equativ Display SDK artifact dependency:
```
dependencies {
 // Add Equativ Display SDK
 implementation 'com.equativ.android:equativ-display-sdk:8.3.0'

 // …
}
```
All dependencies needed by the Equativ Display SDK will be automatically imported by Gradle.

In the android section of your application module build.gradle file, add the Java 8 compile options needed by some imported libraries:

android {
 // …

 compileOptions {
     targetCompatibility = JavaVersion.VERSION_1_8
     sourceCompatibility = JavaVersion.VERSION_1_8
 }
}

You can now proceed with the integration of your ads directly within your project’s workspace.

You can start by integrating a banner ad or an interstitial.

Location

For ad targeting purposes, the Equativ Display SDK can automatically send the latest known user location, if already made available to the application (The Equativ Display SDK will never actively try to retrieve user location).

This automatic location retrieval is disabled by default, and you can enable as follows, provided that one of the location permissions is granted to the application, and that the User consent was properly collected for ad targeting purpose regarding his location.

SASConfiguration.automaticLocationDetectionAllowed = true

Network Security Configuration

Since Android 9 (API level 28), the default network security configuration is not as lenient as it was on previous versions: all network requests must use HTTPS protocol, basic HTTP requests will be blocked by default.

Even though the ad industry progresses towards full HTTPS support, it might happen that some medias are not hosted on secured servers. To avoid your ads being blocked by the default network security configuration, you should create your own network security configuration XML file.

In your res folder, create the folder xml (if not created yet) then inside that folder create a file named network_security_configuration.xml.

Your file must be formatted like this (note: this was the default network security configuration for Android 6.0 (API level 23)):

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="system" />
            <certificates src="user" />
        </trust-anchors>
    </base-config>
</network-security-config>

Once the file created, make sure to add android:networkSecurityConfig="@xml/network_security_config" in the application tag of your AndroidManifest.xml file. For instance:

<application
  android:name=".MyApplication"
  android:icon="@mipmap/ic_launcher"
  android:label="@string/app_name"
  android:networkSecurityConfig="@xml/network_security_config">
</application>