Android Integration Guide

Android Integration Guide | Sport SDK | API Hub

This guide shows the fastest path to a working Android integration:

add the SDK dependency
initialize SportSdk
fetch sports
navigate into seasons, fixtures, and match details

Reference implementation:

androidApp/src/main/java/ag/sportradar/mobile/sdk/sport/android/ui/SampleActivity.kt
androidApp/src/main/java/ag/sportradar/mobile/sdk/sport/android/viewmodel/

Quick start

Add the dependency, call SportSdk.init(...) once, wait for it to finish, and verify the setup with SportControllers.sportsController.getAllSports().

kotlin

dependencies {
    implementation("ag.sportradar.mobile.sdk.sport:sport-sdk:<version>")
}

val initialized = SportSdk.init(
    applicationContext,
    enableAnalytics = true,
    clientConfig = ClientConfig(
        clientId = YOUR_CLIENT_ID,
        appKey = "YOUR_APP_KEY",
        logger = if (BuildConfig.DEBUG) DebugAntilog

#Start here

Install

Use Maven Central in consumer apps, or depend on :sport-sdk locally while developing in this repository.

Initialize

Call SportSdk.init(...) before any controller usage and gate your UI until it completes.

Validate

Use getAllSports() as your first request to confirm credentials and connectivity.

Go deeper

From sports, move to categories, seasons, fixtures, standings, lineups, timeline events, and squads.

#Prerequisites

Android requirements

Android 8.0 / API 26 or later
Kotlin + coroutines

#Installation

note

Replace <version> with the released SDK version your team is onboarding to. Until the Maven Central listing URL is finalized, the artifact coordinates above are the important part.

#Android permissions

Add the required network permissions to your AndroidManifest.xml:

xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
</manifest>

#Quick start

Initialize the SDK before you use any controller.

warning

Do not call SportControllers.* until initialization completes.

note

throwErrorOnInit defaults to false and should only be enabled for testing failure handling.

#First successful request

Start with getAllSports().

kotlin

suspend fun loadSports() {
    val result = SportControllers.sportsController.getAllSports()

    if (result.isSuccess) {
        val sports = result.data.orEmpty()
        println("Loaded ${sports.size} sports")
    } else {
        println("Failed to load sports: ${result.errorMessage}")
    }
}

#Result handling model

#What you get back

Android APIs return CommonResult<T> or typed aliases built on top of it.

Some typed aliases also expose convenience accessors backed by data, for example result.sports, result.matches, result.events, or result.teamSquad.

#What to check

result.isSuccess
result.data
result.errorMessage

#Common aliases

SportsResult = CommonResult<List<Sport>>
SeasonsResult = CommonResult<List<Season>>
StandingsResult = CommonResult<Standings>
FixturesResult = CommonResult<List<Match>>
MatchStatisticsResult = CommonResult<List<MatchStatistics>>

#Public controllers

`SportControllers.sportsController`

Sports, categories, dated matches, and tracked category updates.

`SportControllers.seasonController`

Tournament seasons, tables / standings, and season fixtures.

`SportControllers.matchController`

Statistics, lineups, and soccer timeline events.

`SportControllers.playerController`

Team squad data for a specific team + season pair.

#Sports feed

#Available methods

Method	Returns
`getAllSports()`	`SportsResult`
`getSportCategories(sportId)`	`SportsResult`
`getSportMatchesForDate(timestamp)`	`SportsResult`
`trackSportCategories(sportId)`	`Flow<CommonResult<List<Sport>>>`

#Example ViewModel pattern

kotlin

class SportsViewModel : ViewModel(), InternalKoinComponent {
    private val ioDispatcher: CoroutineDispatcher by inject(qualifier(DispatcherType.IO))
    private val sportsController = SportControllers.sportsController
    private val _sportsState = MutableStateFlow

#Seasons, tables, fixtures, and squad

#ID types to remember

sportId: Long
uniqueTournamentId: Long
seasonId: Long
matchId: Long
teamId: Int

#Match details

#MatchController methods

Method	Returns
`getMatchStatistics(matchId)`	`MatchStatisticsResult`
`getMatchLineups(matchId)`	`MatchLineupsResult`
`getSoccerMatchTimelineEvents(matchId)`	`SoccerTimelineResult`

#Recommended pattern: load in parallel

kotlin

viewModelScope.launch(ioDispatcher) {
    coroutineScope {
        val statisticsDeferred = async { SportControllers.matchController.getMatchStatistics(matchId) }
        val lineupsDeferred = async { SportControllers.matchController.getMatchLineups(matchId) }
        val timelineDeferred = async { SportControllers.matchController.getSoccerMatchTimelineEvents(matchId) }

        val statistics = statisticsDeferred.await

#Working with sealed models

kotlin

when (val stat = matchStatistic) {
    is MatchStatistics.IntStat -> Unit
    is MatchStatistics.DoubleStat -> Unit
    is MatchStatistics.TextStat -> Unit
    is MatchStatistics.BoolStat -> Unit
}

when (val event = soccerEvent) {
    is SoccerEvent.HighlightEvent -> Unit
    is SoccerEvent.StatusUpdate -> Unit
}

#Jetpack Compose example

#Show a minimal Compose screen

kotlin

@Composable
fun SportsScreen(viewModel: SportsViewModel = viewModel()) {
    val state by viewModel.sportsState.collectAsStateWithLifecycle()

    LaunchedEffect(Unit) {
        viewModel.getAllSports()
    }

    when (val loadingStatus = state.loadingStatus) {

#Lifecycle and shutdown

Lifecycle checklist

initialize once before first use
use / for SDK calls

#Proguard / R8

#Add keep rules when your app shrinks aggressively

proguard

-keep class ag.sportradar.mobile.sdk.sport.** { *; }
-keep class ag.sportradar.mobile.sdk.sport.model.** { *; }

#Troubleshooting

#Initialization returns `false`

Check:

clientId is an Int
appKey is correct
your app has a valid application ID (packageName), which the SDK resolves automatically
your project can resolve the SDK artifact from Maven Central

#No data returned

Check:

result.errorMessage
timestamp values are in milliseconds
IDs are the correct type (Long vs Int)

#Controllers crash or fail immediately

Usually this means a controller was accessed before SportSdk.init(...) completed.

#Need logs in development

Attach a logger in ClientConfig:

kotlin

ClientConfig(
    clientId = YOUR_CLIENT_ID,
    appKey = "YOUR_APP_KEY",
    logger = if (BuildConfig.DEBUG) DebugAntilog() else null,
)

kotlin

class SampleActivity : AppCompatActivity() {
    private var sdkInitialized by mutableStateOf(false)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val splashScreen = installSplashScreen()
        splashScreen.setKeepOnScreenCondition { !sdkInitialized }

        lifecycleScope.launch {
            val initialized = SportSdk.init(
                applicationContext,
                enableAnalytics = true,
                clientConfig = ClientConfig(
                    clientId = YOUR_CLIENT_ID,
                    appKey = "YOUR_APP_KEY",
                    logger = if (BuildConfig.DEBUG) DebugAntilog() else null,
                ),
            )

            sdkInitialized = initialized
        }

        setContent {
            if (sdkInitialized) {
                MainScreen()
            }
        }
    }
}

Method	Returns
`getTournamentSeasons(uniqueTournamentId)`	`SeasonsResult`
`getSeasonStanding(seasonId, isCurrentSeason)`	`StandingsResult`
`getSeasonFixtures(seasonId, isCurrentSeason)`	`FixturesResult`

kotlin

val seasonsResult = SportControllers.seasonController.getTournamentSeasons(uniqueTournamentId)
val fixturesResult = SportControllers.seasonController.getSeasonFixtures(seasonId, isCurrentSeason = true)

if (seasonsResult.isSuccess) {
    val seasons = seasonsResult.data.orEmpty()
}

if (fixturesResult.isSuccess) {
    val matches = fixturesResult.data.orEmpty()
}

viewModelScope

lifecycleScope

Android Integration Guide

#Start here

Install

Initialize

Validate

Go deeper

#Prerequisites

#Installation

#Android permissions

#Quick start

#First successful request

#Result handling model

#What you get back

#What to check

#Common aliases

#Public controllers

SportControllers.sportsController

SportControllers.seasonController

SportControllers.matchController

SportControllers.playerController

#Sports feed

#Available methods

Expanded Table

#Example ViewModel pattern

#Seasons, tables, fixtures, and squad

#ID types to remember

#Match details

#MatchController methods

Expanded Table

#Recommended pattern: load in parallel

#Working with sealed models

#Jetpack Compose example

#Show a minimal Compose screen

#Lifecycle and shutdown

#Proguard / R8

#Add keep rules when your app shrinks aggressively

#Troubleshooting

#Initialization returns false

#No data returned

#Controllers crash or fail immediately

#Need logs in development

Initialize the SDK

Gate the UI until initialization completes

Expanded Table

`SportControllers.sportsController`

`SportControllers.seasonController`

`SportControllers.matchController`

`SportControllers.playerController`

#Initialization returns `false`