Android SDK (Core)
Integration Essentials

18min
This section details the configuration process for the NativeWaves SDK, focusing on three critical components: the Graphical User Interface (GUI) Overlay, Content Provider URLs, and Synchronization Settings. The GUI Overlay configures the user interface layer, enhancing user interaction and information display. The Content Provider URL specifies the source for streaming content. Lastly, Synchronization Settings ensure that the app's content is in sync with the user's viewing experience, with options for required, optional, or no synchronization. Together, these settings are fundamental in customizing and optimizing the NativeWaves experience in your application.
Dynamic Orientation and System UI Handling
For an enhanced viewing experience, once you open the EXP View, you can switch to landscape mode and hide the system UI.
Improve user experience by dynamically managing screen orientation and system UI visibility in Jetpack Compose, incorporating configuration changes to handle device orientation and UI mode changes seamlessly.
Handling Config Changes in AndroidManifest
Specify configuration changes in your activity declaration within AndroidManifest.xml to prevent activity restarts on these changes:
XML
<activity android:name=".MainActivity"
android:configChanges="orientation|screenSize|screenLayout|uiMode|smallestScreenSize|locale">
<!-- Other activity configurations -->
</activity>
<activity android:name=".MainActivity"
android:configChanges="orientation|screenSize|screenLayout|uiMode|smallestScreenSize|locale">
<!-- Other activity configurations -->
</activity>
﻿
Adjusting UI Overlays and Orientation
In your Composable function, you can define orientation properties and set the currentRoute if you're utilizing Navigation, as demonstrated in the following code snippet:
Kotlin
val navController = rememberNavController()
val orientation = LocalConfiguration.current.orientation
val activity = LocalContext.current as Activity
val currentRoute = currentRoute(navController = navController)
val navController = rememberNavController()
val orientation = LocalConfiguration.current.orientation
val activity = LocalContext.current as Activity
val currentRoute = currentRoute(navController = navController)
﻿
UI Overlays Based on Orientation
Toggle system UI overlays visibility based on the device's orientation to enhance immersion or provide necessary controls.
Kotlin
LaunchedEffect(orientation) {
    if (orientation == Configuration.ORIENTATION_LANDSCAPE) {
        SystemUiUtils.hideSystemUiOverlay(activity) // app layer function
    } else {
        SystemUiUtils.showSystemUiOverlay(activity) // app layer function
    }
}
LaunchedEffect(orientation) {
    if (orientation == Configuration.ORIENTATION_LANDSCAPE) {
        SystemUiUtils.hideSystemUiOverlay(activity) // app layer function
    } else {
        SystemUiUtils.showSystemUiOverlay(activity) // app layer function
    }
}
﻿
Orientation Based on Navigation Route
Adjust the screen orientation based on the current route, catering to specific content presentation needs.
Kotlin
LaunchedEffect(currentRoute) {
    if (currentRoute?.contains(TAG_EXP_VIEW) == true) {
        activity.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
    } else {
        activity.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
    }
}
LaunchedEffect(currentRoute) {
    if (currentRoute?.contains(TAG_EXP_VIEW) == true) {
        activity.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
    } else {
        activity.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
    }
}
﻿
Notes
TAG_EXP_VIEW is a placeholder for navigation routes requiring landscape mode.
Properly managing config changes and specifying them in the manifest helps in maintaining the application state and user context during orientation changes or when other specified config changes occur.
This approach enables your Jetpack Compose application to dynamically adapt to device orientation changes and user navigation, ensuring an optimal user experience while efficiently handling configuration changes.
﻿Gui Overlay﻿
The GUI Overlay in NwExp for Android and iOS is a dynamic, web-based interface layer that changes based on settings in the NativeWaves Console and the type of event viewed. The URL for this overlay is set by the app using a specific function in the SDK, allowing customization of the user interface to match the event's context and content.
By default, the URL for the web layer is set by the app. For this, the following property is available:
Kotlin
var guiOverlayUrl: String = "<guiOverlayUrl>"
coreSdk.guiOverlayUrl = guiOverlayUrl
var guiOverlayUrl: String = "<guiOverlayUrl>"
coreSdk.guiOverlayUrl = guiOverlayUrl
﻿
The communication with the web layer is done using a CoreSdkUI interface which calls and receives certain events. The interface is being described in the API Reference﻿.
Content Provider (Optional)
The Content Provider in the NativeWaves SDK is a critical component that specifies the source URL for the content associated with a NativeWaves Experience (NwExp). This URL is used to fetch and stream the content relevant to the specified experience, ensuring that users have access to the intended media or event. Set by the application, this URL links the SDK to the appropriate content source, facilitating seamless content delivery and playback within the app.
By default, the URL for the content provider is set by the app. For this, the following property is available:
Kotlin
var contentProviderUrl: String = "<contentProviderUrl>"
coreSdk.contentProviderUrl = contentProviderUrl
var contentProviderUrl: String = "<contentProviderUrl>"
coreSdk.contentProviderUrl = contentProviderUrl
﻿
Audio Sync Configuration﻿
The NativeWaves SDK provides a flexible audio synchronization configuration to align the app's content with the user's viewing experience. The SyncConfig setting determines how synchronization is managed within the SDK.
SyncConfig Settings
NO_SYNC: No synchronization data is required. Use this setting when sync is not a part of the user experience.
SYNC_OPTIONAL and SYNC_ONLY: Synchronization data is required. These settings are used when the app needs to synchronize content with the user's viewing experience.
If developer uses SYNC_OPTIONAL and SYNC_ONLY. It required some properties to initialize the SyncConfig object.
Required Parameters
smdsEndpoint: A mandatory endpoint for synchronization data.
audioSyncMode: Required. Set to CHANNEL (default) or LIBRARY. If not explicitly set to LIBRARY, the default is CHANNEL. Ensure to reset this value when switching, for example, to another showcase.
libraryId: Essential for content synchronization.
Optional Parameters:
directSyncId: Optional, but required if audioSyncMode is set to LIBRARY.
﻿channelId: Optional.﻿
Example Configuration in Code
Kotlin
val enableSync = true // for now, this flag is true by default
val libraryId = "<libraryId>"
val directSyncId: String? = "<directSyncId>"
val smdsEndpoint: NwSmdsEndpoint? = NwSmdsEndpoint("<groupId>", "<url>")


// Configure the synchronization settings
val syncContents = SyncContents(
                    syncConfig = syncConfig,
                    smdsEndpoint = smdsEndpoint,
                    libraryId = libraryId,
                    directSyncId = directSyncIdNullable,
                    audioSyncMode = audioSyncMode,
                )
                
val audioSyncService = coreSdk.audioSyncService(
                        expManifestId = expManifestId,
                        syncContents = syncContents
                    )

val expPlayback = this.experiencePlaybackService(
                        expManifestId = expManifestId,
                        audioSyncService = audioSyncService, // To enable Audio Sync, you have to add this service during initilize experience playback service
                    )
val enableSync = true // for now, this flag is true by default
val libraryId = "<libraryId>"
val directSyncId: String? = "<directSyncId>"
val smdsEndpoint: NwSmdsEndpoint? = NwSmdsEndpoint("<groupId>", "<url>")


// Configure the synchronization settings
val syncContents = SyncContents(
                    syncConfig = syncConfig,
                    smdsEndpoint = smdsEndpoint,
                    libraryId = libraryId,
                    directSyncId = directSyncIdNullable,
                    audioSyncMode = audioSyncMode,
                )
                
val audioSyncService = coreSdk.audioSyncService(
                        expManifestId = expManifestId,
                        syncContents = syncContents
                    )

val expPlayback = this.experiencePlaybackService(
                        expManifestId = expManifestId,
                        audioSyncService = audioSyncService, // To enable Audio Sync, you have to add this service during initilize experience playback service
                    )
﻿
Key Components
Manifest and Library Identifiers:
expManifestId: A unique identifier for the experience manifest, essential for fetching the correct multimedia content.
libraryId: Identifies the content library, assisting in content organization and retrieval.
Synchronization Parameters:
directSyncId: Specifies the identifier for direct synchronization, enabling precise alignment of multimedia content across different platforms or devices.
smdsEndpoint: Configures the synchronization metadata service (SMDS) endpoint, which is crucial for fetching synchronization data.
GUI Overlay URL:
An overlay URL ( overlayUrl) is defined to act as the player's controller, offering additional information and controls over the multimedia content.
Synchronization Configuration:
Determines whether synchronization is enabled ( enableSync) and configures the synchronization settings ( syncConfig) accordingly.
Establishes the audio synchronization mode ( audioSyncMode), which can vary based on the availability and type of synchronization endpoint.
Synchronization Contents Object:
Constructs a SyncContents object with the previously defined synchronization parameters, including the direct synchronization identifier, SMDS endpoint, library identifier, and audio sync mode.
NwCore SDK Configuration:
Sets the SDK environment to production ( NwEnvironment.PROD) and specifies the locale.
Initializes the audio synchronization service with the experience manifest ID and the configured synchronization contents.
Experience Playback Service Initialization:
Utilizes the audioSyncService to initialize the experiencePlaybackService, which is responsible for managing the multimedia content playback.

The synchronization configuration is crucial for a seamless and synchronized user experience.
Ensure the appropriate sync settings are used based on the application's requirements and the type of content being served.
﻿Localization Configuration﻿
The NativeWaves SDK offers localization support by allowing the application to set a specific language code. This feature enables the app to cater to a diverse user base by presenting content in the user's preferred language.
Default Behavior: The SDK defaults to the system's locale. If the system's language isn't supported, it defaults to English ('en'). Currently, supports English ('en') and German ('de').
Setting Language: Use locale: String to set the desired language ('en' or 'de').
If the app requires only the German language ('de'), here is the code snippet to set the locale:
Kotlin
nwCoreSDK.locale = "de" // Sets the language to German
nwCoreSDK.locale = "de" // Sets the language to German
﻿
﻿Environment Type Configuration﻿
 The NativeWaves SDK allows setting the environment type to align with different stages of development and deployment. This is crucial for testing and production purposes.
Default Environment: Production (PROD) is the default. Development (DEV) and Testing (TEST) environments are also available.
Accessing DEV/TEST: Contact NativeWaves support for DEV or TEST environment access. The SDK auto-detects the environment: TEST for debug builds, PROD otherwise.
Setting Environment: Use environment: EnvironmentType to set the desired environment.
If the developers want to try with DEV or TEST environment, here is the code snippet to set the locale:
Kotlin
/*
    enum class EnvironmentType {
        DEV, TEST, PROD;
    }
*/

nwCoreSDK.environment = EnvironmentType.PROD // Sets the environment to Production
/*
    enum class EnvironmentType {
        DEV, TEST, PROD;
    }
*/

nwCoreSDK.environment = EnvironmentType.PROD // Sets the environment to Production
﻿
EnvironmentType Enum Description:
	•	PROD: The Production environment, offering the highest stability and reliability for public use.
	•	TEST: A pre-production environment, quite stable and almost ready for deployment in the production environment.
	•	DEV: The Development environment, where stability is not guaranteed and features may be in experimental stages.
Integrate External Player
Integrate EXP Events
Integration Essentials

Dynamic Orientation and System UI Handling

Handling Config Changes in AndroidManifest

Adjusting UI Overlays and Orientation

Notes

﻿Gui Overlay﻿

Content Provider (Optional)

Audio Sync Configuration﻿

SyncConfig Settings

Required Parameters

Optional Parameters:

Example Configuration in Code

Key Components

﻿Localization Configuration﻿

﻿Environment Type Configuration﻿

Gui Overlay

Audio Sync Configuration

Localization Configuration

Environment Type Configuration
