Android API reference

This page lists the public API of ai.grona:grona-core:0.1.0. Every type is in the package ai.grona.sdk. Methods on Grona and the companion factories are annotated @JvmStatic, so Java callers use them as static methods.

The SDK never throws into your app, with one exception: GronaOptions.Builder.build() throws IllegalArgumentException on invalid input.

Grona

public object Grona

The SDK entry point. Call init once from Application.onCreate. Every other call does nothing until then. Setters are safe from any thread.

Member	Description
const val VERSION: String	The SDK version, "0.1.0". Compared against the minimum SDK version in configurations.
fun init(context: Context, options: GronaOptions, host: GronaHost)	Starts the SDK. Constant time: work is queued off the main thread. Ignored outside the main process and on repeat calls.
fun setConsent(consent: GronaConsent)	Sets the consent state. Defaults to UNKNOWN: events stay in memory and none are sent.
fun identify(customerId: String?)	An opaque internal customer id, never a phone number, email or national id; null on logout. Clears the profile and grants.
fun setProfile(profile: GronaProfile?)	Profile from your own authenticated session. Ignored unless it matches the identified customer.
fun setContext(context: GronaContext)	Sets the shopper context that rules read.
fun setBasket(basket: GronaBasket)	Push a fresh snapshot whenever the basket changes. Live components and decisions re-evaluate.
fun track(event: GronaEvent)	Records a commerce event.
fun decision(anchor: View, placement: String, screen: GronaScreen, listener: GronaDecisionListener): GronaSubscription	Decision for a host-rendered placement, bound to anchor. Main thread only.
fun decision(anchor: View, placement: String, screen: GronaScreen, key: String?, listener: GronaDecisionListener): GronaSubscription	As above, for keyed placements such as cart_line, where key is the line’s product id.
fun activeTreatments(): List<GronaTreatment>	Treatments currently shown to this shopper, each with the grant token your order backend must verify.
fun refresh()	Polls the activation source and asks for a configuration refresh, subject to the 300-second floor. No completion signal.
fun refresh(listener: GronaRefreshListener)	Refreshes now and calls listener once on the main thread when done, also on timeouts, failures and before init.
fun handleLink(uri: Uri): Boolean	Handles <scheme>://grona-preview?.... Returns true when the link was Grona’s, whether or not it was accepted.
fun reset()	Logout or erasure: new install id, and the queue, customer, profile, grants, basket snapshot and preview pins cleared.
fun openDebugView(context: Context)	Opens the debug view when the grona-debug artifact is present and the app is debuggable. Otherwise does nothing.

GronaOptions

public class GronaOptions
public class GronaOptions.Builder(workspaceKey: String)

Options for Grona.init. Build with GronaOptions.Builder. build() throws on invalid input. Each builder method returns the Builder. Every option is also readable as a property of the same name on GronaOptions, except that keys are readable as the maps configKeys and grantKeys.

Builder member	Description
Builder(workspaceKey: String)	The workspace key, a public identifier, not a secret. Must match [A-Za-z0-9._:-]{1,128}.
fun configUrl(url: String)	Signed remote configuration (https). Without it the SDK runs on the bundled copy.
fun bundledConfigAsset(path: String)	Asset path of the signed bundled configuration, applied at launch and offline.
fun configKey(kid: String, publicKeySpki: String)	Trusted configuration signing key: base64 DER SubjectPublicKeyInfo of a P-256 key. Add current and next. At least one is required.
fun grantKey(kid: String, publicKeySpki: String)	Trusted grant signing key, same format as configKey.
fun eventsUrl(url: String)	Events endpoint (https). Without it the SDK sends no events and keeps no event queue. Debuggable builds keep the last 200 events in memory for the debug view.
fun previewUrl(url: String)	Preview pairing endpoint (https). Without it preview links only clear pins.
fun activationSource(source: GronaActivationSource)	Source of on and off answers from an external campaign system.
fun grantSource(source: GronaGrantSource)	Fetches treatment grants from your backend.
fun theme(theme: GronaTheme)	Visual tokens for SDK components.
fun logger(logger: GronaLogger)	Receives SDK diagnostics. Default GronaLogger.NONE.
fun maxAddQuantity(max: Int)	Highest quantity one action may add, 1 to 20. Default 5.
fun maxAddLines(max: Int)	Most lines one action may add, 1 to 20. Default 5.
fun sendPreConsentEvents(enabled: Boolean)	Send events buffered before consent once it is granted. Default false.
fun demoMode(enabled: Boolean)	Demo only, never in production. Takes effect only when the signed configuration also enables demo mode. Default false.
fun build(): GronaOptions	Validates and builds. Throws IllegalArgumentException for an invalid workspace key, a URL that is not https, no configKey, or add caps outside 1 to 20.

GronaHost

public interface GronaHost

Implemented by your app. The SDK calls it only on the main thread and never reaches into app code.

Member	Description
fun product(productId: String): GronaProduct?	Product facts for validation and copy. Must be a fast in-memory lookup; null when unknown.
fun add(lines: List<GronaLine>, source: GronaSource): GronaAddResult	Adds lines after the shopper tapped a Grona call to action.
fun replace(productId: String, with: GronaLine, source: GronaSource): GronaAddResult	Replaces one basket line, for example an out-of-stock item with its substitute.
fun navigate(route: GronaRoute, source: GronaSource): Boolean	Opens route with your own router; false when the route is unknown.

GronaSlotView

public class GronaSlotView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
) : FrameLayout

A place in your layout where Grona renders native components: banner, progress, offer and message. With nothing to show it stays laid out at zero height. Never set it GONE or INVISIBLE.

Member	Description
var placement: String	The placement. Usually set in XML with app:gronaPlacement. Set it before screen.
var screen: GronaScreen?	Starts the slot; rules read it. An equal value continues the visit; null ends it.

GronaScreen

public class GronaScreen

Where the shopper is. Rules read it.

Member	Description
val type: String	The screen type, such as home or product.
val productId: String?	The product, for product screens.
val categoryId: String?	The category, for category screens.
val treatmentTypes: List<String>	For order confirmation: treatments your order backend applied.
val name: String?	Your name for an other screen.
HOME, CATEGORIES, SEARCH, CART, CHECKOUT	Fixed screens.
fun category(categoryId: String): GronaScreen	A category listing.
fun product(productId: String): GronaScreen	A product page.
fun orderConfirmation(treatmentTypes: List<String>): GronaScreen	Order confirmation. treatmentTypes are the treatments your order backend actually applied.
fun other(name: String): GronaScreen	Any other screen.

GronaBasket

public class GronaBasket
public class GronaBasket.Builder(currency: String)

Basket snapshot pushed with Grona.setBasket. Money is in minor units.

Member	Description
Builder(currency: String)	The currency code, such as USD.
fun line(productId: String, qty: Int, unitPriceMinor: Long, inStock: Boolean): Builder	Adds one basket line.
fun totalMinor(total: Long): Builder	The total rules compare against; defaults to the sum of the lines.
fun build(): GronaBasket	Builds the snapshot.
GronaBasket.empty(currency: String): GronaBasket	An empty basket.

GronaContext

public class GronaContext
public class GronaContext.Builder()

Shopper context that rules can read. Signed-in state comes from Grona.identify.

Member	Description
fun locale(locale: String): Builder	The shopper’s locale. Default "en".
fun branchId(id: String?): Builder	Your store or branch id. Default null.
fun deliveryType(type: String?): Builder	Your delivery type. Default null.
fun build(): GronaContext	Builds the context.

GronaProfile

public class GronaProfile
public class GronaProfile.Builder(customerId: String)

Per-shopper data from your authenticated session, bound to one customer id. Segment ids are opaque.

Member	Description
Builder(customerId: String)	The customer the profile belongs to.
fun segment(id: String): Builder	Adds one segment id.
fun segments(ids: Collection<String>): Builder	Adds several segment ids.
fun list(name: String, productIds: List<String>): Builder	Sets a named list of product ids.
fun attribute(name: String, value: String): Builder	Sets a string attribute.
fun build(): GronaProfile	Builds the profile.

GronaEvent

public class GronaEvent

Commerce events your app forwards from its analytics layer. Money is in minor units; no search text, no full baskets. Exception: on keyed placements such as cart_line, campaign events carry the line’s product id as their key, in every arm. So while a cart_line campaign is live, the product ids of the cart lines bound to it leave the device.

Member	Description
fun viewItem(productId: String, priceMinor: Long): GronaEvent	A product view.
fun addToCart(productId: String, qty: Int, priceMinor: Long): GronaEvent	A cart add.
fun removeFromCart(productId: String, qty: Int): GronaEvent	A cart removal.
fun beginCheckout(totalMinor: Long): GronaEvent	Checkout started.
fun purchase(orderId: String, totalMinor: Long, productIds: List<String>, treatments: List<GronaTreatment>): GronaEvent	A confirmed order. productIds is the whole order; the SDK keeps only those Grona campaigns showed or added.

GronaDecision

public class GronaDecision

A product decision your app renders with its own views. Treat unknown types as no decision.

Member	Description
val placement: String	The placement.
val campaignId: String	The campaign.
val variantId: String	The variant.
val type: String	rail, bundle, substitute or product_card.
val title: String?, val subtitle: String?, val badge: String?, val ctaLabel: String?	Copy from the configuration. Render as plain text.
val products: List<GronaDecisionProduct>	The products to show.
val key: String?	For keyed placements such as cart_line: the line this decision belongs to.
val extras: Map<String, String>	Layout hints from the configuration, such as position for feed rows. Untrusted.
val isPreview: Boolean	true while a preview pin produced this decision.
val source: GronaSource	Placement, campaign and variant.
fun add(productId: String): GronaAddResult	Call from the shopper’s tap. The SDK validates, logs the action and calls GronaHost.add.
fun add(productId: String, qty: Int): GronaAddResult	As above, with a quantity.
fun addAll(): GronaAddResult	Adds every product in the decision.
fun replace(withProductId: String): GronaAddResult	Replaces key with withProductId through GronaHost.replace.
fun dismiss()	Hides this decision for the rest of the session.
RAIL, BUNDLE, SUBSTITUTE, PRODUCT_CARD	Type constants: "rail", "bundle", "substitute", "product_card".

GronaDecisionProduct

Member	Description
val productId: String	The product.
val qty: Int	The quantity addAll adds.
val label: String?	A per-product label from the configuration.

Listeners and subscriptions

Type	Member	Description
fun interface GronaDecisionListener	fun onDecision(decision: GronaDecision?)	Receives decisions on the main thread; null means show nothing.
fun interface GronaRefreshListener	fun onRefreshed()	Completion of Grona.refresh; called once on the main thread.
fun interface GronaSubscription	fun cancel()	Ends the decision’s subscription and its visit.
	GronaSubscription.NONE	A subscription that does nothing, returned before init.

GronaTreatment

public class GronaTreatment

A money-bearing treatment. Display state only: your order backend applies it only after verifying token.

Member	Description
val campaignId: String	The campaign.
val variantId: String	The variant.
val placement: String	Where it was shown.
val type: String	The treatment type.
val valueMilli: Long	Value in thousandths, so 10000 is 10 (10% off with percent_off).
val token: String?	Grona-signed grant (compact JWS); null in demo mode. A real backend ignores a treatment without a token: no treatment, and the order still goes through.
val isDemo: Boolean	true for a demo-mode treatment.

Value types

Type	Members	Description
enum class GronaConsent	UNKNOWN, GRANTED, DENIED	The shopper’s consent state.
enum class GronaAddResult	ACCEPTED, PARTIAL, REJECTED	The outcome of an add or replace.
class GronaLine(productId: String, qty: Int)	val productId: String, val qty: Int; secondary constructor GronaLine(productId: String) with qty 1	One product and quantity in an action.
class GronaSource	val placement: String, val campaignId: String, val variantId: String	Which campaign and variant an action came from.
class GronaRoute	val type: String, val id: String?	A typed destination your app resolves itself. Grona never passes raw links.
	HOME, PRODUCT, CATEGORY, CART, CHECKOUT, DEALS	Route type constants: "home", "product", "category", "cart", "checkout", "deals". Unknown types may arrive from newer configurations; return false from GronaHost.navigate for them.

GronaProduct

public class GronaProduct
public class GronaProduct.Builder(productId: String, name: String, priceMinor: Long)

Product facts from your app. Money is in minor units. Each builder value is also readable as a property: productId, name, priceMinor, wasPriceMinor, imageUri, inStock.

Member	Description
Builder(productId: String, name: String, priceMinor: Long)	Id, display name and price.
fun wasPriceMinor(price: Long?): Builder	A previous price. Default null.
fun imageUri(uri: String?): Builder	The product image. Default null.
fun inStock(inStock: Boolean): Builder	Whether it can be added. Default true.
fun build(): GronaProduct	Builds the product.

GronaTheme

public class GronaTheme
public class GronaTheme.Builder()

Visual tokens so SDK components match your app. Each value is also readable as a property: fontRegular, fontBold, primary, onPrimary, accent, surface, text, mutedText, cornerRadiusDp.

Member	Default
fun fonts(regular: Typeface?, bold: Typeface?): Builder	null, null
fun primary(color: Int): Builder	0xFF054B3A
fun onPrimary(color: Int): Builder	0xFFFFFFFF
fun accent(color: Int): Builder	0xFF6FCF97
fun surface(color: Int): Builder	0xFFFFFFFF
fun text(color: Int): Builder	0xFF1A1C1A
fun mutedText(color: Int): Builder	0xFF6B706C
fun cornerRadiusDp(radius: Float): Builder	14f
fun build(): GronaTheme

See Theming for what each token colours.

Callbacks your app implements

Type	Member	Description
fun interface GronaLogger	fun log(priority: Int, message: String)	Receives SDK diagnostics. Silent by default; never given customer ids, baskets, tokens or keys.
	GronaLogger.NONE	The silent default.
fun interface GronaActivationSource	fun activeExternalIds(): Set<String>?	On and off answers from an external campaign system. Called on a Grona background thread; may block up to 10 seconds. null when unknown. Activation can only switch campaigns off.
fun interface GronaGrantSource	fun fetchGrants(customerId: String): List<String>?	Fetches grants from your backend, which asks Grona’s server for them. Called on a Grona background thread; may block up to 10 seconds. Compact JWS grants, or null on failure.

Note

The package ai.grona.sdk.debug holds the internal API that grona-debug uses. It requires an opt-in that fails the build by default, is not part of the public API, and may change in any release.