# TryYourSize Android SDK reference

---

# Android reference (TryYourSize for Kotlin)

> The native Size guide button (Compose and Views), the shopper's recommended size, and the TryYourSize window.

Source: https://docs.tryyoursize.com/reference/android/

*SDK* · `com.tryyoursize:tryyoursize-android` · v0.1.0

minSdk 24, Jetpack Compose and Views. The window needs an androidx `ComponentActivity` (for example `AppCompatActivity`). Register your app for the key in Studio as `android-app://<package>` (test mode today; live mode for apps is coming soon).

## Install

**Gradle (Kotlin)**

```kotlin
dependencies { implementation("com.tryyoursize:tryyoursize-android:0.1.0") }
```

## Initialize

**Kotlin**

```kotlin
val tys = TryYourSize(context, "pk_test_…") // a secret key throws
```

**Swift**

```swift

let tys = try TryYourSize(publishableKey: "pk_test_…") // a secret key throws
```

Error codes: [Mobile SDK errors](https://docs.tryyoursize.com/mobile/errors.md).

## Client

| | |
|---|---|
| [`constructor`](https://docs.tryyoursize.com/reference/android/constructor.md) | Creates the client for your publishable key. |
| [`Configuration`](https://docs.tryyoursize.com/reference/android/configuration.md) | TryYourSize.Configuration |
| [`recommendation()`](https://docs.tryyoursize.com/reference/android/recommendation.md) | The shopper's recommended size for a product, in your size labels. |
| [`getRecommendation()`](https://docs.tryyoursize.com/reference/android/get-recommendation.md) | The same, with a callback (Java). |
| [`onRecommendation()`](https://docs.tryyoursize.com/reference/android/on-recommendation.md) | Calls handler now (once known) and on every change: signing in, a new body, a simulation finishing. |
| [`on (events)`](https://docs.tryyoursize.com/reference/android/on.md) | Window events: Ready, Open, Close, Size, LoadError. |
| [`present()`](https://docs.tryyoursize.com/reference/android/present.md) | Opens the measuring / try-on window for a product, full screen over activity. |
| [`appearance`](https://docs.tryyoursize.com/reference/android/appearance-property.md) | Live restyle (e.g. |
| [`appOrigin`](https://docs.tryyoursize.com/reference/android/app-origin.md) | android-app://<package>: what the store registers as an allowed origin. |

## Size guide button

| | |
|---|---|
| [`SizeGuide`](https://docs.tryyoursize.com/reference/android/size-guide.md) | The "Size guide" button: "Size guide" → "Calculating your size…" → "Your size: M". |
| [`SizeGuideView`](https://docs.tryyoursize.com/reference/android/size-guide-view.md) | The same button as an Android View: set client and product. |

## Types

| | |
|---|---|
| [`Recommendation`](https://docs.tryyoursize.com/reference/android/recommendation-type.md) | The shopper's recommended size for one product, in the store's own size labels. |
| [`Appearance`](https://docs.tryyoursize.com/reference/android/appearance.md) | Colours (ARGB ints), font and corner radius for the button and the window. |
| [`TryYourSizeException`](https://docs.tryyoursize.com/reference/android/errors.md) | Every error the SDK raises: a stable code, a message and a doc link (like the web SDK). |

---

# appOrigin

> android-app://<package>: what the store registers as an allowed origin.

Source: https://docs.tryyoursize.com/reference/android/app-origin/

*Property* · `com.tryyoursize:tryyoursize-android`

`android-app://<package>`: what the store registers as an allowed origin.

```kotlin
public val appOrigin: String
```

## Example

**Kotlin**

```kotlin
Log.i("tys", tys.appOrigin) // "android-app://com.brand.shop": add it in Studio
```

---

# appearance

> Live restyle (e.g.

Source: https://docs.tryyoursize.com/reference/android/appearance-property/

*Property* · `com.tryyoursize:tryyoursize-android`

Live restyle (e.g. when your app switches to dark theme); an open window updates at once.

```kotlin
public var appearance: Appearance
```

## Example

**Kotlin**

```kotlin
tys.appearance = tys.appearance.copy(colorPrimary = 0xFF3B2F26.toInt())
```

**Swift**

```swift
tys.appearance.colorPrimary = TYSColor(hex: "#3b2f26") // an open window restyles at once
```

**React Native**

```tsx
setAppearance({ variables: { colorPrimary: "#3b2f26" } });
```

**Flutter**

```dart
await tys.setAppearance(const Appearance(colorPrimary: Color(0xFF3B2F26)));
```

---

# Appearance

> Colours (ARGB ints), font and corner radius for the button and the window.

Source: https://docs.tryyoursize.com/reference/android/appearance/

*Type* · `com.tryyoursize:tryyoursize-android`

Colours (ARGB ints), font and corner radius for the button and the window. With `INHERIT` (default) they follow your app theme, dark included.

## Properties

- **`theme`** (`Theme`, optional, default `Theme.INHERIT`)
- **`colorPrimary`** (`Int?`, optional, default `null`): ARGB colour ints (android.graphics.Color / Compose `toArgb()`). Buttons, the tape line, the "connected" dot.
- **`colorBackground`** (`Int?`, optional, default `null`)
- **`colorText`** (`Int?`, optional, default `null`)
- **`fontFamily`** (`String?`, optional, default `null`): A CSS font-family for the window (e.g. "Inter, Roboto, sans-serif"). The native button uses the Compose text style where it is placed.
- **`borderRadius`** (`Float?`, optional, default `null`): Corner radius in dp (0–32) for cards, inputs and buttons.
- **`fonts`** (`List<String>`, optional, default `emptyList()`): Stylesheets with @font-face rules for the window (Google Fonts only).

## Example

**Kotlin**

```kotlin
val tys = TryYourSize(context, "pk_test_…", TryYourSize.Configuration(
    appearance = Appearance(borderRadius = 10f),
    locale = "es",
))
```

**Swift**

```swift
let tys = try TryYourSize(publishableKey: "pk_test_…", configuration: .init(
    appearance: Appearance(borderRadius: 10),
    locale: "es"))
```

**React Native**

```tsx
await configure("pk_test_…", { appearance: { variables: { borderRadius: 10 } }, locale: "es" });
```

**Flutter**

```dart
final tys = await TryYourSize.create('pk_test_…', appearance: const Appearance(borderRadius: 10), locale: 'es');
```

---

# TryYourSize.Configuration

> TryYourSize.Configuration

Source: https://docs.tryyoursize.com/reference/android/configuration/

*Type* · `com.tryyoursize:tryyoursize-android`

## Properties

- **`appearance`** (`Appearance`, optional, default `Appearance()`): Colours, font and corner radius for the button and the window.
- **`locale`** (`String?`, optional, default `null`): BCP 47 language for the button and the window; null: the device's language.
- **`packageName`** (`String?`, optional, default `null`): The app's identity registered for the store; null: the context's package name.
- **`embedOrigin`** (`String`, optional, default `"https://embed.tryyoursize.com"`): Our window's origin (change only for staging or local development).
- **`webContentsDebugging`** (`Boolean`, optional, default `false`): Lets chrome://inspect attach to the window. Debug builds only.

## Example

**Kotlin**

```kotlin
val tys = TryYourSize(context, "pk_test_…", TryYourSize.Configuration(
    appearance = Appearance(borderRadius = 10f),
    locale = "es",
))
```

**Swift**

```swift
let tys = try TryYourSize(publishableKey: "pk_test_…", configuration: .init(
    appearance: Appearance(borderRadius: 10),
    locale: "es"))
```

**React Native**

```tsx
await configure("pk_test_…", { appearance: { variables: { borderRadius: 10 } }, locale: "es" });
```

**Flutter**

```dart
final tys = await TryYourSize.create('pk_test_…', appearance: const Appearance(borderRadius: 10), locale: 'es');
```

---

# TryYourSize(context, publishableKey, configuration)

> Creates the client for your publishable key.

Source: https://docs.tryyoursize.com/reference/android/constructor/

*Constructor* · `com.tryyoursize:tryyoursize-android`

Creates the client for your publishable key. Keep one per app.

```kotlin
public class TryYourSize @JvmOverloads constructor(
    context: Context,
    public val publishableKey: String,
    public val configuration: Configuration = Configuration(),
)
```

## Parameters

- **`context`** (`Context`, required): Any context; the application context is kept.
- **`publishableKey`** (`String`, required): Your publishable key (`pk_test_…` / `pk_live_…`).
- **`configuration`** (`Configuration`, optional, default `Configuration()`): See `Configuration`(/reference/android/configuration/).

## Errors

`TryYourSizeException` with code `SECRET_KEY_IN_APP`, `INVALID_KEY`, `INVALID_APP_IDENTIFIER` or `INVALID_OPTION`.

## Example

**Kotlin**

```kotlin
val tys = TryYourSize(context, "pk_test_…", TryYourSize.Configuration(
    appearance = Appearance(borderRadius = 10f),
    locale = "es",
))
```

**Swift**

```swift
let tys = try TryYourSize(publishableKey: "pk_test_…", configuration: .init(
    appearance: Appearance(borderRadius: 10),
    locale: "es"))
```

**React Native**

```tsx
await configure("pk_test_…", { appearance: { variables: { borderRadius: 10 } }, locale: "es" });
```

**Flutter**

```dart
final tys = await TryYourSize.create('pk_test_…', appearance: const Appearance(borderRadius: 10), locale: 'es');
```

---

# TryYourSizeException

> Every error the SDK raises: a stable code, a message and a doc link (like the web SDK).

Source: https://docs.tryyoursize.com/reference/android/errors/

*Type* · `com.tryyoursize:tryyoursize-android`

Every error the SDK raises: a stable `code`, a message and a doc link (like the web SDK).

Each error has a `code` (its `wire` value is the documented code), a message and a `docUrl`. Explanations: [Mobile SDK errors](https://docs.tryyoursize.com/mobile/errors.md).

## Codes

- **`SECRET_KEY_IN_APP`** (`"secret_key_in_app"`, optional): A secret (`sk_`) or restricted (`rk_`) key was passed. Those belong on your server.
- **`INVALID_KEY`** (`"invalid_key"`, optional): Not a publishable key (`pk_test_…` / `pk_live_…`).
- **`INVALID_APP_IDENTIFIER`** (`"invalid_app_identifier"`, optional): The package name can't be used as an app origin.
- **`INVALID_OPTION`** (`"invalid_option"`, optional)
- **`WINDOW_UNREACHABLE`** (`"window_unreachable"`, optional): Our window did not answer (offline, or blocked).
- **`APP_NOT_ALLOWED`** (`"app_not_allowed"`, optional): This app (`android-app://<package>`) is not registered for the key's store.
- **`SIGN_IN_CANCELLED`** (`"sign_in_cancelled"`, optional)
- **`SIGN_IN_UNAVAILABLE`** (`"sign_in_unavailable"`, optional): System-browser sign-in is not available yet.

## Example

**Kotlin**

```kotlin
try {
    tys = TryYourSize(context, key)
} catch (e: TryYourSizeException) {
    if (e.code == TryYourSizeException.Code.SECRET_KEY_IN_APP) error("Use the pk_ key")
}
```

---

# getRecommendation()

> The same, with a callback (Java).

Source: https://docs.tryyoursize.com/reference/android/get-recommendation/

*Method* · `com.tryyoursize:tryyoursize-android`

The same, with a callback (Java).

```kotlin
public fun getRecommendation(product: String, callback: (Result<Recommendation>) -> Unit)
```

## Parameters

- **`product`** (`String`, required): Your product ID or SKU.
- **`callback`** (`(Result<Recommendation>) -> Unit`, required): Called once with the result.

## Example

**Kotlin**

```kotlin
tys.getRecommendation("SKU-123") { result ->
    result.onSuccess { rec -> if (rec.status == Recommendation.Status.READY) selected = rec.size }
}
```

---

# onRecommendation()

> Calls handler now (once known) and on every change: signing in, a new body, a simulation finishing.

Source: https://docs.tryyoursize.com/reference/android/on-recommendation/

*Method* · `com.tryyoursize:tryyoursize-android`

Calls `handler` now (once known) and on every change: signing in, a new body, a simulation finishing. Keep the subscription; `cancel()` it when done. Main thread.

```kotlin
@JvmOverloads
public fun onRecommendation(
        product: String,
        onError: ((TryYourSizeException) -> Unit)? = null,
        handler: (Recommendation) -> Unit,
    ): TysSubscription
```

## Parameters

- **`product`** (`String`, required): Your product ID or SKU.
- **`onError`** (`((TryYourSizeException) -> Unit)?`, optional, default `null`): Called when our window cannot be reached or the app is not registered.
- **`handler`** (`(Recommendation) -> Unit`, required): Called now (once known) and on every change.

## Returns

A subscription; `cancel()` it when done.

## Example

**Kotlin**

```kotlin
val sub = tys.onRecommendation("SKU-123") { rec ->
    if (rec.status == Recommendation.Status.READY && !touched) selected = rec.size
}
// sub.cancel() in onDestroy
```

**Swift**

```swift
let sub = tys.onRecommendation(for: "SKU-123") { rec in
    if rec.status == .ready, !touched { selectedSize = rec.size }
}
// keep `sub`; sub.cancel() when the screen goes away
```

**React Native**

```tsx
useEffect(() => {
  const sub = addRecommendationListener("SKU-123", (rec) => {
    if (rec.status === "ready" && !touched) setSize(rec.size);
  });
  return () => sub.remove();
}, []);
```

**Flutter**

```dart
final sub = tys.onRecommendation('SKU-123').listen((rec) {
  if (rec.status == RecommendationStatus.ready && !touched) setState(() => size = rec.size);
});
// sub.cancel() in dispose()
```

---

# on()

> Window events: Ready, Open, Close, Size, LoadError.

Source: https://docs.tryyoursize.com/reference/android/on/

*Method* · `com.tryyoursize:tryyoursize-android`

Window events: Ready, Open, Close, Size, LoadError.

```kotlin
public fun on(handler: (Event) -> Unit): TysSubscription
```

## Parameters

- **`handler`** (`(Event) -> Unit`, required): Called with each window event.

## Events

- **`Ready(val product: String)`** (optional): The window is shown and connected.
- **`Open(val product: String)`** (optional)
- **`Close(val product: String)`** (optional)
- **`Size(val selection: SizeSelection)`** (optional): The shopper chose a size: preselect it.
- **`LoadError(val error: TryYourSizeException)`** (optional): Our window could not be reached, or this app is not registered for the key.

## Returns

A subscription; `cancel()` stops the events.

## Example

**Kotlin**

```kotlin
val sub = tys.on { event ->
    when (event) {
        is TryYourSize.Event.Size -> selected = event.selection.size
        is TryYourSize.Event.LoadError -> Log.w("tys", event.error.code.wire)
        else -> Unit
    }
}
```

**Swift**

```swift
let sub = tys.on { event in
    switch event {
    case .size(let selection): selectedSize = selection.size   // "Use this size"
    case .loadError(let error): print(error.code)
    default: break
    }
}
```

**React Native**

```tsx
const sub = addEventListener((e) => {
  if (e.type === "size") setSize(e.selection.size);
  if (e.type === "loaderror") console.warn(e.code);
});
```

**Flutter**

```dart
tys.events.listen((e) {
  if (e is SizeSelected) setState(() => size = e.selection.size);
  if (e is LoadError) debugPrint(e.error.code);
});
```

---

# present()

> Opens the measuring / try-on window for a product, full screen over activity.

Source: https://docs.tryyoursize.com/reference/android/present/

*Method* · `com.tryyoursize:tryyoursize-android`

Opens the measuring / try-on window for a product, full screen over `activity`.

```kotlin
@JvmOverloads
public fun present(activity: ComponentActivity, product: String, step: OpenStep? = null)
```

## Parameters

- **`activity`** (`ComponentActivity`, required): An androidx `ComponentActivity`.
- **`product`** (`String`, required): Your product ID or SKU.
- **`step`** (`OpenStep?`, optional, default `null`): `OpenStep.CREATE`, `IMPROVE` or `VIEW`.

## Example

**Kotlin**

```kotlin
tys.present(activity, "SKU-123")                // or step = OpenStep.VIEW
```

**Swift**

```swift
tys.present(product: "SKU-123")                 // or step: .view, from: viewController
```

**React Native**

```tsx
present("SKU-123");                             // or present("SKU-123", "view")
```

**Flutter**

```dart
await tys.present('SKU-123');                   // or step: OpenStep.view
```

---

# Recommendation

> The shopper's recommended size for one product, in the store's own size labels.

Source: https://docs.tryyoursize.com/reference/android/recommendation-type/

*Type* · `com.tryyoursize:tryyoursize-android`

The shopper's recommended size for one product, in the store's own size labels.

## Properties

- **`product`** (`String`, required)
- **`status`** (`Status`, required)
- **`size`** (`String?`, optional, default `null`): The recommended size in the store's label (its size map), or null.
- **`studioSize`** (`String?`, optional, default `null`): The same size as entered in TryYourSize Studio, or null.
- **`wearableSizes`** (`List<String>?`, optional, default `null`): Sizes that can be worn on this body, in the store's labels (when simulated).

## Example

**Kotlin**

```kotlin
lifecycleScope.launch {
    val rec = tys.recommendation("SKU-123")
    if (rec.status == Recommendation.Status.READY) selected = rec.size
}
```

**Swift**

```swift
let rec = try await tys.recommendation(for: "SKU-123")
if rec.status == .ready, let size = rec.size { selectedSize = size }
```

**React Native**

```tsx
const rec = await getRecommendation("SKU-123");
if (rec.status === "ready") setSize(rec.size);
```

**Flutter**

```dart
final rec = await tys.recommendation('SKU-123');
if (rec.status == RecommendationStatus.ready) setState(() => size = rec.size);
```

## Notes

`status`: `READY`, `COMPUTING`, `NO_SIZE` (`"none"` on the web), `SIGNED_OUT`, `UNAVAILABLE`.

---

# recommendation()

> The shopper's recommended size for a product, in your size labels.

Source: https://docs.tryyoursize.com/reference/android/recommendation/

*Method* · `com.tryyoursize:tryyoursize-android`

The shopper's recommended size for a product, in your size labels. Never starts a simulation; never carries measurements or body data. Main thread.

```kotlin
public suspend fun recommendation(product: String): Recommendation
```

## Parameters

- **`product`** (`String`, required): Your product ID or SKU.

## Returns

The shopper's recommended size. See [Recommendation](https://docs.tryyoursize.com/reference/android/recommendation-type.md).

## Example

**Kotlin**

```kotlin
lifecycleScope.launch {
    val rec = tys.recommendation("SKU-123")
    if (rec.status == Recommendation.Status.READY) selected = rec.size
}
```

**Swift**

```swift
let rec = try await tys.recommendation(for: "SKU-123")
if rec.status == .ready, let size = rec.size { selectedSize = size }
```

**React Native**

```tsx
const rec = await getRecommendation("SKU-123");
if (rec.status === "ready") setSize(rec.size);
```

**Flutter**

```dart
final rec = await tys.recommendation('SKU-123');
if (rec.status == RecommendationStatus.ready) setState(() => size = rec.size);
```

---

# SizeGuideView (Views)

> The same button as an Android View: set client and product.

Source: https://docs.tryyoursize.com/reference/android/size-guide-view/

*Component* · `com.tryyoursize:tryyoursize-android`

The same button as an Android `View`: set `client` and `product`.

## Parameters

- **`context`** (`Context`, required)
- **`attrs`** (`AttributeSet?`, optional, default `null`)
- **`defStyleAttr`** (`Int`, optional, default `0`)

## Properties

- **`client`** (`TryYourSize?`, required): Your client.
- **`product`** (`String?`, required): Your product ID or SKU.
- **`variant`** (`SizeGuideVariant`, required): `LINK` (default) or `BUTTON`.
- **`label`** (`String?`, required): Your own words instead of "Size guide".
- **`onRecommendation`** (`((Recommendation) -> Unit)?`, required): The shopper's recommended size, on show and on every change.

## Example

**Kotlin**

```kotlin
// Views
val guide = SizeGuideView(context).apply {
    client = tys
    product = "SKU-123"
    variant = SizeGuideVariant.BUTTON
    onRecommendation = { rec -> /* … */ }
}
```

**Swift**

```swift
// UIKit
let guide = SizeGuideButton(client: tys, product: "SKU-123", variant: .button)
guide.onRecommendation = { rec in /* … */ }
stack.addArrangedSubview(guide)
```

---

# SizeGuide (Compose)

> The "Size guide" button: "Size guide" → "Calculating your size…" → "Your size: M".

Source: https://docs.tryyoursize.com/reference/android/size-guide/

*Component* · `com.tryyoursize:tryyoursize-android`

The "Size guide" button: "Size guide" → "Calculating your size…" → "Your size: M". A tap opens the window.

```kotlin
@Composable
public fun SizeGuide(
    client: TryYourSize,
    product: String,
    modifier: Modifier = Modifier,
    variant: SizeGuideVariant = SizeGuideVariant.LINK,
    label: String? = null,
    textStyle: TextStyle = TextStyle(fontSize = 15.sp),
    onRecommendation: ((Recommendation) -> Unit)? = null,
)
```

## Parameters

- **`client`** (`TryYourSize`, required): Your client.
- **`product`** (`String`, required): Your product ID or SKU.
- **`modifier`** (`Modifier`, optional, default `Modifier`): Compose modifier.
- **`variant`** (`SizeGuideVariant`, optional, default `SizeGuideVariant.LINK`): `LINK` (32 dp tall, 48 dp touch target) or `BUTTON`.
- **`label`** (`String?`, optional, default `null`): your own words instead of "Size guide".
- **`textStyle`** (`TextStyle`, optional, default `TextStyle(fontSize = 15.sp)`): your text style (font, size); the colour defaults to the app theme's text colour.
- **`onRecommendation`** (`((Recommendation) -> Unit)?`, optional, default `null`): the shopper's recommended size, on show and on every change (sizes only).

## Example

**Kotlin**

```kotlin
// Compose, where your "Size guide" link was
SizeGuide(tys, "SKU-123", textStyle = MaterialTheme.typography.bodyMedium) { rec ->
    if (rec.status == Recommendation.Status.READY && !touched) selected = rec.size
}
```

**Swift**

```swift
// SwiftUI, where your "Size guide" link was
SizeGuide(client: tys, product: "SKU-123") { rec in
    if rec.status == .ready, !touched { selectedSize = rec.size }
}
```

**React Native**

```tsx
<SizeGuide
  product="SKU-123"
  onRecommendation={(rec) => rec.status === "ready" && !touched && setSize(rec.size)}
/>
```

**Flutter**

```dart
const SizeGuide(product: 'SKU-123') // listen to tys.onRecommendation to preselect
```