App Banner

App Banner Integration

App Banner returns the selected banner content as JSON. Your app is responsible for parsing the JSON and rendering the native UI.

Important

App Banner requires OmniSegment Android SDK 1.1.0 or later and Android minSdk 24 or later.

Before you start

Make sure that:

• The SDK is installed and initialized with your API key and TID.
• You have received the pageKey and bannerKey configured for the banner.
• Your app can display the banner's image or video content.

pageKey identifies the current app screen. bannerKey identifies the banner on that screen. Both values must be non-empty and match the values configured in OmniSegment.

The SDK does not create a View or insert content into a WebView.

Note

SDK 1.1.0 depends on androidx.webkit:webkit:1.16.0. If your project uses Kotlin 1.8, verify dependency resolution before release because transitive dependencies may use incompatible Kotlin metadata.

Banner content

delivery.contentJSON contains the selected banner content as a JSON string.

A card banner can look like this:

{
  "type": "card",
  "card": {
    "image": {
      "enabled": true
    },
    "image_src": [
      {
        "url": "https://cdn.example.com/banner.mp4",
        "type": "video"
      }
    ],
    "title": {
      "enabled": true,
      "text": "Banner title"
    },
    "description": {
      "enabled": true,
      "text": "Banner description"
    },
    "ctaButton": {
      "enabled": true,
      "text": "Learn more"
    },
    "closeButton": {
      "enabled": true
    },
    "redirectUrl": "https://example.com"
  }
}

Use the top-level type to select the banner renderer. The media source in image_src can be either an image or a video:

• When the media source type is video, render its url with a video player.
• Otherwise, render the url as an image. Image data may not include a type.
• Do not load the media when image.enabled is false.
• Handle media loading failures without blocking the banner's remaining content.
• Stop and release video playback when the banner or screen is removed.

For each optional block, check enabled before rendering it and handle missing or null values safely. The available fields may vary with the banner configuration, so the app should ignore fields it does not use.

Request and display a banner

The callback is asynchronous and runs on the Android main thread. Keep the returned request while the screen needs the result. Keep the delivery while the displayed banner can still be clicked or closed.

import androidx.appcompat.app.AppCompatActivity
import com.bebittech.omnisegment.OSGBannerContentDelivery
import com.bebittech.omnisegment.OSGBannerContentStatus
import com.bebittech.omnisegment.OSGBannerRequest
import com.bebittech.omnisegment.OmniSegment

class HomeActivity : AppCompatActivity() {
    private var bannerRequest: OSGBannerRequest? = null
    private var bannerDelivery: OSGBannerContentDelivery? = null

    override fun onStart() {
        super.onStart()
        loadBanner()
    }

    private fun loadBanner() {
        bannerRequest = OmniSegment.requestBannerContent("home", "home_top") { result ->
            bannerRequest = null

            when (result.status) {
                OSGBannerContentStatus.CONTENT -> {
                    val delivery = result.delivery ?: return@requestBannerContent

                    renderBanner(delivery.contentJSON) {
                        bannerDelivery = delivery
                        delivery.reportDisplayed()
                    }
                }

                OSGBannerContentStatus.NO_CONTENT -> {
                    bannerDelivery = null
                    hideBanner()
                }

                OSGBannerContentStatus.FAILED -> {
                    bannerDelivery = null
                    hideBanner()
                    handleBannerError(result.error?.code)
                }
            }
        }
    }

    fun onBannerClicked() {
        bannerDelivery?.reportClicked()
    }

    fun onBannerClosed() {
        bannerDelivery?.reportClosed()
        bannerDelivery = null
        hideBanner()
    }

    override fun onStop() {
        bannerRequest?.cancel()
        bannerRequest = null
        super.onStop()
    }
}

renderBanner, hideBanner, and handleBannerError are placeholders for your app's UI code; they are not SDK methods.

Call reportDisplayed() only after the banner is actually visible. Call reportClicked() and reportClosed() when those actions occur. Each method is safe to call more than once for the same delivery.

Result status

Status	delivery	error	Recommended handling
CONTENT	Present	null	Parse delivery.contentJSON, render the banner, and report its lifecycle events.
NO_CONTENT	null	null	Hide the banner or leave the area empty. This is not an error.
FAILED	null	Present	Hide the banner and inspect result.error?.code.

Error codes

Code	Meaning
INVALID_ARGUMENT	pageKey or bannerKey is empty or contains only whitespace.
NOT_INITIALIZED	OmniSegment.initialize(...) has not been called.
NETWORK	A network request failed.
TIMED_OUT	The request took too long to complete.
INVALID_CONTENT	The returned content could not be parsed.
INTERNAL	An unexpected error occurred.

Cancellation

Call cancel() when the screen no longer needs a pending result. A cancelled request does not call its completion handler.

bannerRequest?.cancel()
bannerRequest = null

Do not cancel the request immediately after creating it.

Java request example

private OSGBannerRequest bannerRequest;
private OSGBannerContentDelivery bannerDelivery;

private void loadBanner() {
    bannerRequest = OmniSegment.requestBannerContent("home", "home_top", result -> {
        bannerRequest = null;

        if (result.getStatus() == OSGBannerContentStatus.CONTENT) {
            OSGBannerContentDelivery delivery = result.getDelivery();
            if (delivery == null) {
                return;
            }

            renderBanner(delivery.getContentJSON(), () -> {
                bannerDelivery = delivery;
                delivery.reportDisplayed();
            });
        } else if (result.getStatus() == OSGBannerContentStatus.NO_CONTENT) {
            bannerDelivery = null;
            hideBanner();
        } else {
            bannerDelivery = null;
            hideBanner();
            handleBannerError(result.getError() == null ? null : result.getError().getCode());
        }
    });
}