Skip to main content

Getting Started with Reachu Kotlin SDK

Get up and running with the Reachu Kotlin SDK in your Android application or backend service in just a few minutes.

Prerequisites​

  • Android StudioHedgehog (2023.1.1) or later
  • Android 5.0+(API 21+) for Android apps
  • JDK 17or later
  • Kotlin 1.9+ - Gradle 8.0+ - A Reachu account with API credentials
Quick Start

The entire setup takes less than 5 minutes! Just add the dependency, create a config file, and you're ready to build amazing shopping experiences.

Step 1: Installation​

For Android Projects​

Add the SDK to your build.gradle.kts:

build.gradle.kts (Project level)
buildscript {
 repositories {
 google()
 mavenCentral()
 }
}

allprojects {
 repositories {
 google()
 mavenCentral()
 // Add Reachu repository
 maven {
 url = uri("https://your-registry.repo")
 }
 }
}

build.gradle.kts (App level)
dependencies {
 // Core SDK
 implementation("io.reachu:reachu-kotlin-sdk:1.0.0")
 
 // Optional: Jetpack Compose UI components
 implementation("io.reachu:reachu-ui-compose:1.0.0")
 
 // Required: Coroutines
 implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
 
 // Required: Jetpack Compose (if using UI components)
 implementation("androidx.compose.ui:ui:1.5.4")
 implementation("androidx.compose.material3:material3:1.1.2")
}

For Backend Services (JVM)​

build.gradle.kts
dependencies {
 implementation("io.reachu:reachu-kotlin-sdk:1.0.0")
 implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}

Maven​

pom.xml
<dependencies>
 <dependency>
 <groupId>io.reachu</groupId>
 <artifactId>reachu-kotlin-sdk</artifactId>
 <version>1.0.0</version>
 </dependency>
</dependencies>

Step 2: Configuration​

Create Configuration File​

Create a reachu-config.json file in your assets folder (Android) or resources folder (JVM):

reachu-config.json
{
 "contexts": {
 "app": {
 "defaultEnvironment": "production",
 "environments": {
 "production": {
 "apiKey": "YOUR_API_KEY",
 "baseUrl": "https://graph-ql-prod.reachu.io/graphql",
 "marketFallback": {
 "countryCode": "NO",
 "currencyCode": "NOK"
 }
 },
 "development": {
 "apiKey": "YOUR_DEV_API_KEY",
 "baseUrl": "https://graph-ql-dev.reachu.io/graphql",
 "marketFallback": {
 "countryCode": "NO",
 "currencyCode": "NOK"
 }
 }
 }
 }
 }
}

Initialize SDK​

Android Application​

Application.kt
import android.app.Application
import io.reachu.ReachuCore.configuration.ConfigurationLoader

class MyApplication : Application() {
 override fun onCreate() {
 super.onCreate()
 
 // Load configuration from assets/reachu-config.json
 ConfigurationLoader.loadConfiguration(context = this)
 }
}

Don't forget to register it in AndroidManifest.xml:

AndroidManifest.xml
<application
 android:name=".MyApplication"
 ...>
</application>

Backend Service​

Main.kt
import io.reachu.sdk.core.SdkClient
import java.net.URL

fun main() {
 val sdk = SdkClient(
 baseUrl = URL("https://graph-ql-prod.reachu.io/graphql"),
 apiKey = "YOUR_API_KEY"
 )
 
 // Use SDK...
}

Step 3: Basic Usage​

Initialize Cart Manager​

MainActivity.kt
import androidx.compose.runtime.*
import io.reachu.ReachuUI.Managers.CartManager
import io.reachu.ReachuUI.Components.CheckoutDraft

class MainActivity : ComponentActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
 super.onCreate(savedInstanceState)
 
 val cartManager = remember { CartManager() }
 val checkoutDraft = remember { CheckoutDraft() }
 
 setContent {
 MyApp(cartManager, checkoutDraft)
 }
 }
}

Add Products to Cart​

ProductView.kt
import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import io.reachu.ReachuUI.Managers.CartManager
import kotlinx.coroutines.launch

@Composable
fun ProductView(product: Product, cartManager: CartManager) {
 val scope = rememberCoroutineScope()
 
 Button(
 onClick = {
 scope.launch {
 cartManager.addProduct(
 productId = product.id,
 quantity = 1
 )
 }
 }
 ) {
 Text("Add to Cart")
 }
}

Show Checkout Overlay​

CheckoutScreen.kt
import androidx.compose.runtime.*
import io.reachu.ReachuUI.Components.RCheckoutOverlay
import io.reachu.ReachuUI.Components.RCheckoutOverlayCompose

@Composable
fun CheckoutScreen(
 cartManager: CartManager,
 checkoutDraft: CheckoutDraft,
 onDismiss: () -> Unit
) {
 val checkoutOverlay = remember {
 RCheckoutOverlay(cartManager, checkoutDraft)
 }
 
 RCheckoutOverlayCompose(
 overlay = checkoutOverlay,
 onDismiss = onDismiss
 )
}

Step 4: Environment Variables (Optional)​

You can override configuration using environment variables:

# Set environment variables
export REACHU_API_TOKEN="your-api-key"
export REACHU_BASE_URL="https://graph-ql-prod.reachu.io/graphql"
export REACHU_CONFIG_TYPE="app"
export REACHU_ENVIRONMENT="production"

The SDK will use these variables if the config file is not found.

Step 5: Verify Installation​

Create a simple test to verify everything works:

SdkTest.kt
import io.reachu.sdk.core.SdkClient
import kotlinx.coroutines.runBlocking
import java.net.URL

fun main() = runBlocking {
 val sdk = SdkClient(
 baseUrl = URL("https://graph-ql-prod.reachu.io/graphql"),
 apiKey = "YOUR_API_KEY"
 )
 
 // Test: Get available markets
 val markets = sdk.market.getAvailable()
 println("Available markets: ${markets.size}")
 
 // Test: Create cart
 val cart = sdk.cart.create(
 customerSessionId = "test-${System.currentTimeMillis()}",
 currency = "NOK",
 shippingCountry = "NO"
 )
 println("Cart created: ${cart.cartId}")
}

Next Steps​

Troubleshooting​

Common Issues​

Issue: Configuration file not found

  • Solution: Ensure reachu-config.json is in assets folder (Android) or resources folder (JVM)

Issue: API key invalid

  • Solution: Verify your API key in the Reachu dashboard

Issue: Network error

  • Solution: Check your internet connection and verify the baseUrl is correct

Issue: Coroutine scope error

  • Solution: Ensure you're using coroutines correctly and have the coroutines dependency

Need Help?​

Ready to build?

Continue to Payment Integration →:::