Android SDK Setup

To integrate AppsOnAir-AppLink Android SDK to your Android native Apps with Kotlin, follow the below steps

BETA

The plugin is fully functional and integrates with our AppLink service, which is currently in public beta. While you can start using it today, please note that there may be minor changes or improvements as we prepare for full production launch.

Basic Requirements for Service Usage

apiKey Setup

• Make sure to configure the API key properly. For additional information Getting started

Prerequisites

• Before getting started, ensure your AppLink Configuration is set up.

• Install or update Android Studio to its latest version.
• Make sure that your project meets these requirements:
  • Android Gradle Plugin (AGP): Version 8.0.2 or higher
  • Kotlin: Version 1.7.10 or higher
  • Gradle: Version 8.0 or higher

Add AppsOnAir AppLink in Gradle Plugin and SDK

Newer versions of Android Studio

When creating a new project from Android Studio Artic Fox (or newer) the allprojects{...} is no longer added in the project level gradle.so need add in settings.gradle

Groovy

settings.gradle

dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
       ...
       maven { url 'https://jitpack.io' }
   }
}

Kotlin

settings.gradle.kts

dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
       ...
       maven("https://jitpack.io")
   }
}

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Open Your Root build.gradle File and Add the Following

Groovy

build.gradle

    allprojects {
    repositories {
            ...
      maven { url 'https://jitpack.io' }
    }
  }

Kotlin

build.gradle.kts

    allprojects {
    repositories {
            ...
      maven("https://jitpack.io")
    }
  }

Add the Following to Your dependencies Section

libs.versions.toml

    [versions]
    appsonairAndroidApplink = "Tag" // latest version

    [libraries]
    appsonair-android-applink = { module = "com.github.apps-on-air:AppsOnAir-Android-AppLink", version.ref = "appsonairAndroidApplink" }

app/build.gradle

    dependencies {
      implementation(libs.appsonair.android.applink)
  }

Sync Gradle

Make sure to press "Sync Now" on the banner that pops up after saving!

Add Required Code

• Add below code to the app's AndroidManifest.xml file under the activity tag of your main activity.

AndroidManifest.xml

<intent-filter android:autoVerify="true">
   <action android:name="android.intent.action.VIEW" />
   <category android:name="android.intent.category.DEFAULT" />
   <category android:name="android.intent.category.BROWSABLE" />
    <data
     android:host="your domain"
     android:scheme="https" />
</intent-filter>

• Add below code if you are using custom uri scheme.

AndroidManifest.xml

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
     android:host="open"
     android:scheme="your scheme" />
</intent-filter>

Add the AppLink Service Initialization Code and Usage

To initialize the AppLink we recommend adding the initialization code within the onCreate method of your Main Launcher Activity (MainActivity).

Kotlin

MainActivity.kt

import com.appsonair.applink.interfaces.AppLinkListener
import com.appsonair.applink.services.AppLinkService

class MainActivity : AppCompatActivity() {
    private val TAG = "MainActivity"
    private lateinit var deepLinkService: AppLinkService
   override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Initialize deepLink service and set listener for deep link and referral link events
        deepLinkService = AppLinkService.getInstance(this)
        // Initialize the AppLink to track the deepLink
        deepLinkService.initialize(this, intent, object : AppLinkListener {
            override fun onDeepLinkProcessed(uri: Uri, result: JSONObject) {
                // Store the processed deep link URL and log the parameters
            }

            override fun onDeepLinkError(uri: Uri?, error: String) {
                // Handle error when deep link processing fails
            }
        })
    }
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        deepLinkService.handleDeepLink(
            intent,
            "com.example.appsonair_android_applink"
        ) 
    }
}

java

MainActivity.java

import com.appsonair.applink.interfaces.AppLinkListener;
import com.appsonair.applink.services.AppLinkService;

public class MainActivity extends AppCompatActivity {
 private AppLinkService deeplinkService;
 private String deepLinkUrl = "";


 @Override
 protected void onCreate(Bundle savedInstanceState) {
     // Initialize deeplink service and set listener for deep link and referral link events
     deeplinkService = AppLinkService.Companion.getInstance(this);

     // Initialize the AppLink to track the deeplink and referral tracking
     deeplinkService.initialize(this, getIntent(), new AppLinkListener() {
         @Override
         public void onDeepLinkProcessed(@NonNull Uri uri, @NonNull JSONObject jsonObject) {
             // Handle deep link here
         }

         @Override
         public void onDeepLinkError(@Nullable Uri uri, @NonNull String s) {
         // Handle error here
         }
     });
     super.onCreate(savedInstanceState);

 }
 @Override
 protected void onNewIntent(Intent intent) {
     super.onNewIntent(intent);

     if (deeplinkService != null) {
         // Handle deep link first
         deeplinkService.handleDeepLink(
                 intent,
                 "com.example.appsonair_android_applink",
                 null,
                 null
         );
     }
 }
}

• The initialize() function initializes the common AppLink service and sets up the deep link handler. It processes the incoming link when the app is launched with an intent and uses an AppLinkListener to handle the success or failure of deep link processing.

Add the Code for Creating the AppLink and Usage

To create the AppLink, you can call the createAppLink method inside an onClick listener or wherever you need it.

Kotlin

MainActivity.kt

import com.appsonair.applink.services.AppLinkService

class MainActivity : AppCompatActivity() {
    private val TAG = "MainActivity"
    private lateinit var deepLinkService: AppLinkService
   override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Initialize deepLink service and set listener for deep link and referral link events
        deepLinkService = AppLinkService.getInstance(this)
        val socialMeta = mapOf(
            "title" to "link title",
            "description" to "link description",
            "imageUrl" to "https://image.png"
        )

        // Create the AppLink
        val result = deepLinkService.createAppLink(
            name = "AppsOnAir",
            url = "https://appsonair.com",
            urlPrefix = "YOUR_DOMAIN_NAME", //shouldn't contain http or https
            shortId = "LINK_ID",
            socialMeta = socialMeta,
            androidFallbackUrl = "www.playstore/app.com",
            iOSFallbackUrl = "www.appstore/app.com",
        )
    }
}

java

MainActivity.java

package com.example.appsonair_android_applink.util;
import com.appsonair.applink.services.AppLinkService;

// The createAppLink method is a Kotlin suspend function, which means it’s designed to be called from a coroutine.
//But Java doesn't support coroutines or suspend functions directly, so you can’t call createAppLink from Java without help.

// to use suspend function create a new Kotlin file (you can name it AppLinkBridge.kt) it will work as your bridge
class AppLinkBridge {
    companion object{
        @JvmStatic
        fun createAppLinkBlocking(
            context: Context,
            url: String,
            name: String,
            urlPrefix: String,
            shortId: String? = null,
            socialMeta: Map<String, Any>? = null,
            isOpenInBrowserAndroid: Boolean = false,
            isOpenInAndroidApp: Boolean = true,
            androidFallbackUrl: String? = null,
            isOpenInBrowserApple: Boolean = false,
            isOpenInIosApp: Boolean = true,
            iOSFallbackUrl: String? = null,
        ): JSONObject = kotlinx.coroutines.runBlocking {
            createAppLink(
                context,
                url,
                name,
                urlPrefix,
                shortId,
                socialMeta,
                isOpenInBrowserAndroid,
                isOpenInAndroidApp,
                androidFallbackUrl,
                isOpenInBrowserApple,
                isOpenInIosApp,
                iOSFallbackUrl
            )
        }

        // Move your suspend function here or keep it in the same file
        private suspend fun createAppLink(
            context: Context,
            url: String,
            name: String,
            urlPrefix: String,
            shortId: String? = null,
            socialMeta: Map<String, Any>? = null,
            isOpenInBrowserAndroid: Boolean = false,
            isOpenInAndroidApp: Boolean = true,
            androidFallbackUrl: String? = null,
            isOpenInBrowserApple: Boolean = false,
            isOpenInIosApp: Boolean = true,
            iOSFallbackUrl: String? = null,
        ): JSONObject {
            return AppLinkService.getInstance(context).createAppLink(
                name = name,
                url = url,
                urlPrefix = urlPrefix,
                shortId = shortId,
                socialMeta = socialMeta,
                isOpenInBrowserAndroid = isOpenInBrowserAndroid,
                isOpenInAndroidApp = isOpenInAndroidApp,
                androidFallbackUrl = androidFallbackUrl,
                isOpenInBrowserApple = isOpenInBrowserApple,
                isOpenInIosApp = isOpenInIosApp,
                iOSFallbackUrl = iOSFallbackUrl,
            )
        }
    }
}

// Now you can use this in your java file and create your applinks like below

package com.example.appsonair_android_applink.util;
import com.appsonair.applink.interfaces.AppLinkListener;
import com.appsonair.applink.services.AppLinkService;

public class MainActivity extends AppCompatActivity {
    private AppLinkService deeplinkService;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Initialize deeplink service and set listener for deep link and referral link events
        deeplinkService = AppLinkService.Companion.getInstance(this);
        Map<String, Object> meta = new HashMap<>();
        meta.put("title", "link title");
        meta.put("description", "link description");
        meta.put("imageUrl", "https://image.png");
        JSONObject result =   AppLinkBridge.createAppLinkBlocking(
                this,
                "https://example.com",
                "AppLink",
                "https://example.applink",
                null,              // shortId
                meta,              // socialMeta
                false,             // isOpenInBrowserAndroid
                true,              // isOpenInAndroidApp
                null,              // androidFallbackUrl
                false,             // isOpenInBrowserApple
                true,              // isOpenInIosApp
                null               // iOSFallbackUrl
        );
    }
}

AppLinkParams Properties

Defines all parameters used to construct a AppLink, including app URL, fallbacks, short ID, and social-meta.

Key	Description
url	The actual deep link URL that the app should open. Example: myapp://product/123
name	The name or label for the link, often used for internal identification.
urlPrefix	The base URL prefix for the link (e.g., https://app.domain.com/). This helps create a complete shareable link.
androidFallbackUrl	A web URL to redirect users to when the app is not installed on Android devices.
iOSFallbackUrl	A web URL to redirect users to when the app is not installed on iOS devices.
shortId	An optional short ID to make the link shorter and easier to share. If provided, the final link becomes urlPrefix/shortId
socialMeta	Meta information used for social sharing previews. refer SocialMeta Properties
isOpenInBrowserApple	Determines whether the link should open in the browser on Apple devices (iOS/macOS).
isOpenInIosApp	Specifies if the link should open in the iOS app even if your app is installed.
isOpenInAndroidApp	Indicates whether to open the link in the Android app even if your app is installed.
isOpenInBrowserAndroid	Determines if the link should open in the browser on Android devices.

socialMeta Properties

Key	Description
title	The title to show in social media link previews.
description	A short description used in social sharing cards (Facebook, Twitter, etc.).
imageUrl	A URL to an image that will appear in the social media preview.

Add the Code for Retrieving the Referral Link and Usage

To get the AppLink referral information, you can call the getReferralDetails() method on onCreate, onClick or wherever you need it.

Kotlin

MainActivity.kt

import com.appsonair.applink.services.AppLinkService

class MainActivity : AppCompatActivity() {
    private val TAG = "MainActivity"
    private lateinit var deepLinkService: AppLinkService
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Initialize deepLink service and set listener for deep link and referral link events
        deepLinkService = AppLinkService.getInstance(this)
        // Get the referral information
        val referral = deepLinkService.getReferralDetails()
    }
}

java

MainActivity.java

import com.appsonair.applink.services.AppLinkService;

public class MainActivity extends AppCompatActivity {
    private AppLinkService deeplinkService;
    private String deepLinkUrl = "";

    private AppBarConfiguration appBarConfiguration;
    private ActivityMainBinding binding;
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Initialize deeplink service and set listener for deep link and referral link events
        deeplinkService = AppLinkService.Companion.getInstance(this);
        JSONObject result =   deeplinkService.getReferralDetails();
    }
}

• getReferralDetails() is used for get the latest referral information.

Response

{
  "data": {
    "shortId": "linkId",
    "referralLink": "https://your.referral.link"
  }
}

Run Your App and Set Up Your AppLink Services

Run your app by using Android Studio on Android simulators or any physical device to make sure it builds correctly.

For more details explore the example