# Getting Started with the DT Ignite Services SDK

Integrating the DT Ignite Services (DTIS) SDK with your Host App allows you to connect to and interact with the Ignite client that is present on a device. The connection allows you to check for apps on the device, retrieve app metadata, install apps from the Ignite ecosystem, and launch apps after installation.

The following diagram provides an overview of how your Host App uses the DTIS SDK to communicate with Ignite on the device.

{% @mermaid/diagram content="sequenceDiagram
participant Host as Host App
participant SDK as Ignite

```
Host->>SDK: Initialize and Connect via Ignite Services SDK
SDK->>SDK: Authenticate
Host->>SDK: Call SDK Methods

opt callback and/or broadcast
    SDK-->>Host: Task notifications
end

Host->>Host: Process notifications
Host->>SDK: Disconnect" %}
```

To integrate the DT Ignite Services (DTIS) SDK into your Host App:

* [Step 1: Set Up the DTIS SDK](#setup)
* [Step 2: Call SDK Methods](#call)
* [Step 3: Test Your Integration](#test)
* [Step 4: Prepare Host App for Production](#production)

## Step 1: Set Up the DTIS SDK <a href="#setup" id="setup"></a>

To set up the DTIS SDK:

1. Obtain a `clientID` from DT.\
   The `clientID` identifies your Host App in the DT environment.
2. Provide the `clientID` in the `meta-data` tag of the `AndroidManifest.xml` file for your Host app.

{% code title="XML" %}

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.mycompany.myapp">

    <application ... >
		...

		<!-- Example Client ID -->
		<meta-data
    		 android:name="com.digitalturbine.ignite.aidl.CLIENT_ID"
	    	 android:value="52093f98-63a7-45b4-b9fb-191c685d6a40" />
	</application>
</manifest>
```

{% endcode %}

3. Add `ignite-service-aidl-sdk.aar` to your `libs/` folder in your project, or, if you use shared sources, import it as as a module.

## Step 2: Call SDK Methods <a href="#call" id="call"></a>

The DTIS SDK offers methods that allow you to interact with Ignite on a device. For a complete list of use cases and the appropriate methods to call, see [Use Cases](https://docs.digitalturbine.com/dt-ignite/ignite-services/use-cases).

To call DTIS SDK methods in your Host App:

1. Declare and connect an instance of `IIgniteService.kt`. Once connected, the DTIS SDK automatically authenticates the Host App using the credentials stored in `AndroidManifest.xml`. The DTIS SDK also manages the session and any subsequent token refreshes. For more information, see [Connect to Ignite](https://docs.digitalturbine.com/dt-ignite/ignite-services/sdk-reference/connect-to-ignite).

{% code title="Kotlin" %}

```kotlin
lateinit var igniteService: IIgniteService

// ...

// After SDK is initialized, the IgniteService instance is returned.
// It can also be retrieved later using IgniteServiceSdk.instance()
// NOTE: `clientSecret` can be empty for initial integration
igniteService = IgniteServiceSdk.init(context, clientSecret)
// ...
IgniteServiceSdk.instance().connect(object: IConnectionCallback {
     override fun onConnected() {
          // Connection with Ignite is established
          Toast.makeText(applicationContext, "Connected.", Toast.LENGTH_SHORT).show()
     }

	 override fun onAuthenticated() {
	      // Client is now able to call API methods
          Toast.makeText(applicationContext, "Authenticated.", Toast.LENGTH_SHORT).show()
     }

     override fun onDisconnected(message: String?) {
          Toast.makeText(applicationContext, "Disconnected from Ignite Service: $message", Toast.LENGTH_SHORT).show()
     }
})

// or

igniteService.connect(this)
```

{% endcode %}

2. Call DTIS SDK methods according to the [SDK Reference](https://docs.digitalturbine.com/dt-ignite/ignite-services/sdk-reference).

{% code title="Kotlin" %}

```kotlin
findViewById<Button>(R.id.version).setOnClickListener {
    val result = IgniteServiceSdk.instance().version()
    Toast.makeText(applicationContext, "SDK version: ${result?.sdkVersion}, Ignite version: ${result?.igniteVersion}", Toast.LENGTH_SHORT).show()
}
```

{% endcode %}

3. Disconnect from Ignite. For more information, see [Disconnect from Ignite](https://docs.digitalturbine.com/dt-ignite/ignite-services/sdk-reference/disconnect-from-ignite).

{% code title="Kotlin" %}

```kotlin
// ...

IgniteServiceSdk.instance().disconnect(this)

// ...
```

{% endcode %}

## Step 3: Test Your Integration <a href="#test" id="test"></a>

To test your DTIS integration, ensure that your test environment meets the following requirements:

* Ignite is installed on the test device. For more information about installing Ignite on a device, contact your DT Representative.
* Host App is integrated with DTIS and installed on the test device.
* Host App fingerprint and signing certificate are unique to Testing environment.

## Step 4: Prepare Host App for Production <a href="#production" id="production"></a>

Once you have completed testing your Host App, create a Production version of your Host App that uses a unique fingerprint and signing certificate that are different from the from those used in the testing environment.

## Example: Full Integration <a href="#h_01k3sbt7gtar00kdw5rqwzph04" id="h_01k3sbt7gtar00kdw5rqwzph04"></a>

The following example code shows a full integration using the DTIS SDK.

A fully integrated demo application is available on request for existing customers. For access to the demo application, contact your DT Representative.

{% code title="Kotlin" %}

```kotlin
class MainActivity : AppCompatActivity(), IConnectionCallback {
    // Remember instance or you can call IgniteServiceSdk.instance()
    lateinit var igniteService: IIgniteService

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        igniteService = IgniteService(applicationContext)
        igniteService.connect(this)

        // Call remote function on button click
        findViewById<Button>(R.id.version).setOnClickListener {
            val result = igniteService.version()
            Toast.makeText(applicationContext, "SDK version: ${result?.sdkVersion}, Ignite version: ${result?.igniteVersion}", Toast.LENGTH_SHORT).show()
        }

        findViewById<Button>(R.id.install).setOnClickListener {
            val file = File("${requireContext().filesDir}", "myfungame.apk")
            val data = file.toUri().toString()
            
            igniteService.install(data, object : IResponseCallback<InstallationResponse, Error, InstallationProgress> {
                override fun onSuccess(result: InstallationResponse) {
                    Log.d("InstallApp","onSuccess(): taskId=${result.taskId}, appId=${result.applicationId}, package=${result.packageName}, partnerMetadata=${result.partnerMetaData}")
                }

                override fun onError(error: Error) {
                    Log.d("InstallApp","onError(): message=${error.message}, code=${error.code}, partnerMetadata=${error.partnerMetadata}")
                }
            })
        }

        // Other API methods
    }

    override fun onConnected() {
        Toast.makeText(applicationContext, "Connected to Ignite Service", Toast.LENGTH_SHORT).show()
    }

    override fun onAuthenticated() {
        Toast.makeText(applicationContext, "Authenticated", Toast.LENGTH_SHORT).show()
    }

    override fun onDisconnected(message: String?) {
        Toast.makeText(applicationContext, "Disconnected from Ignite Service: $message", Toast.LENGTH_SHORT).show()
    }

    override fun onDestroy() {
        super.onDestroy()
        igniteService.disconnect(this)
    }
}
```

{% endcode %}