SDKs and a clean integration

Choose the right SDK

The backend JVM SDK calls the Platform API. Android/Swift mobile packages communicate with your authenticated backend relay. The mobile location package evaluates proximity. These packages have independent versions and readiness; a backend API key must never be embedded in a mobile application.

Backend JVM: signed private Maven

Current published evaluation version: io.hailme.platform:hailme-platform-sdk-jvm:0.1.0-dev.3. Use JDK 17. Request an individual Maven reader credential and the verified bootstrap. Access to Maven is separate from your project service key.

Maven origin: https://hailme-sdk-maven.dymnov-dm.workers.dev/maven

Keep HAILME_MAVEN_USER and HAILME_MAVEN_TOKEN in private environment/secret storage. The supplied client pins the publisher signing key and third-party dependency checksums. Do not disable signature verification when a download fails. Obtain the trusted bootstrap hash and pinned verification metadata through the authenticated onboarding channel.

repositories {
    exclusiveContent {
        forRepository {
            maven {
                url = uri("https://hailme-sdk-maven.dymnov-dm.workers.dev/maven")
                credentials {
                    username = providers.environmentVariable("HAILME_MAVEN_USER").get()
                    password = providers.environmentVariable("HAILME_MAVEN_TOKEN").get()
                }
            }
        }
        filter { includeGroup("io.hailme.platform") }
    }
    mavenCentral()
}
dependencies {
    implementation("io.hailme.platform:hailme-platform-sdk-jvm:0.1.0-dev.3")
}

This is the repository/dependency excerpt. For signature verification and a reproducible new project use the complete supplied bootstrap project, not this excerpt alone. No platform source checkout, server JAR, database or Redis is needed.

Create and observe a notification

The following belongs in a suspend function. Load the TEST key from your backend secret store. Persist request and operationKey in your own outbox before calling.

import io.hailme.platform.sdk.*
import io.hailme.platform.sdk.model.*
import java.time.Instant
import java.util.UUID

val request = CreateSmsNotification(
    recipient = CreateSmsNotificationRecipient("+12025550131"),
    templateId = "sandbox.sms.v1",
    locale = "en",
    parameters = mapOf("message" to "Hello from my backend"),
    expiresAt = Instant.now().plusSeconds(300).toString(),
    clientReference = "first-test"
)
val operationKey = UUID.randomUUID().toString()
val client = HailMeClient(
    "https://platform-staging.hailme.app",
    ServiceKeyProvider { ServiceKey(System.getenv("HAILME_PLATFORM_TEST_KEY")) }
)
try {
    val admitted = client.createSms(request, operationKey)
    val current = client.notification(UUID.fromString(admitted.id))
    val counters = client.usage()
} finally {
    client.close()
}

The SDK supports SMS, push, templates, installations, usage counters and webhook verification. Default transport makes one attempt; opt-in retry is bounded and preserves the original operation. Never create a new business operation to recover an unknown result. Use the same immutable request and key after a lost response. Check the cabinet ledger for money, rather than multiplying SDK counters.

Verify and new channels

Published dev.3 has no typed Verify, WhatsApp, Telegram, Signal or general email methods. Call the documented Verify HTTP API from your backend while it is TEST/FAKE. Adding documentation does not change an already published immutable JAR. A future SDK release must add and verify typed methods before claiming them available.

Mobile and location packages

Android/Swift evaluation packages remain version 0.1.0-dev.1. They demonstrate installation lifecycle and forwarding via a host relay, with synthetic examples. The location package demonstrates foreground proximity and synthetic trips. Real device background tracking, native permission behavior and production customer integration require separate acceptance. Do not promise these packages as a production courier-tracking service.

Clean-project acceptance

Use the trusted bootstrap outside the platform repository. Verify signatures, build offline fixtures, then run one TEST send, exact replay, status polling and budget rejection. Inspect the owner cabinet and costs CSV. Revoke the temporary key after evaluation. No real provider credentials, production data or platform sources are required.