connect-kotlin-sdk

connect-kotlin-sdk is a Kotlin library that makes it easier to generate valid Connect URLs that lets your users to link their accounts to Gandalf.

Features

• Generate valid Connect URLs
• Parameter validation

Getting Started

This section provides a quick overview of how to integrate the library into your project.

Prerequisites

• Kotlin: >= v1.8.8
• Gradle: >= v8.8
• JDK: >= v17

Installation

Using Gradle

To integrate GandalfConnect into your project, add it to your build.gradle.kts or build.gradle file:

build.gradle.kts

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

dependencies {
    implementation("com.github.gandalf-network:connect-kotlin-sdk:1.0.2")
}

build.gradle

repositories {
    mavenCentral()
    maven {
        url 'https://jitpack.io'
    }
}

dependencies {
    implementation 'com.github.gandalf-network:connect-kotlin-sdk:1.0.2'
}

Using Maven

To integrate GandalfConnect into your project, add it to your pom.xml file:

build.gradle.kts

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.gandalf-network</groupId>
        <artifactId>connect-kotlin-sdk</artifactId>
        <version>1.0.2</version>
    </dependency>
</dependencies>

Usage

Importing the Library

In your Kotlin file where you want to use GandalfConnect, import the library:

// The Connect class
import com.gandalf.connect.Connect

// Useful Types
import com.gandalf.connect.types.ConnectInput
import com.gandalf.connect.types.InputData
import com.gandalf.connect.types.Service

Initialization

Create an instance of ConnectInput with the necessary details:

val publicKey = ""
val redirectURL = "https://example.com"
val services: InputData = mutableMapOf(
    "uber" to Service(traits = listOf("rating"), activities = listOf("trip")),
    // You can add multiple services
    "netflix" to Service(traits = listOf("rating"), activities = listOf("trip"), required = false), // the required prop is used to make a service optional
)

// Optional paramter to modify the Connect UI
val style = StylingOptions(
    primaryColor = "#FF0000", 
    backgroundColor = "#0000FF", 
    foregroundColor = "#fff", 
    accentColor = "#562ba6"
)
val options: ConnectOptions =  ConnectOptions(style)

val connectInput = ConnectInput(publicKey, redirectURL, services, options)

Initialize the Connect class:

val connect = Connect(connectInput)

Generating URL

To generate a URL, call the generateURL method:

runBlocking {
    try {
        val generatedURL = connect.generateURL()
        println("Generated URL: $generatedURL")
    } catch (e: Exception) {
        println("Error: ${e.message}")
    }
}

Validations

The generateURL method performs several validations:

• Public Key Validation: Ensures the public key is valid.
• Redirect URL Validation: Checks if the redirect URL is properly formatted.
• Input Data Validation: Verifies that the input data conforms to the expected structure and contains supported services and traits/activities.

Getting Data Key from URL

To extract the data key from a URL:

runBlocking {
    try {
        val dataKey = Connect.getDataKeyFromURL("https://example.com/?dataKey=a100")
        println("DataKey: $dataKey")
    } catch(Exception e) {
        println("Error: ${e.message}")
    }
}

Contributing

We would love you to contribute to connect-kotlin-sdk, pull requests are welcome! Please see the CONTRIBUTING.md for more information.

License

The scripts and documentation in this project are released under the MIT License