Surfaces - Auxia Docs

A surface is a location in your application where treatments can appear. Surfaces define the “where” of treatment delivery — the specific screen, page, or touchpoint a user is on when they receive a treatment.

Surface Identification and API Usage

Immediately below is an example of how the surface field is used in a Get Treatments API request. Each surface is identified by a name written in SCREAMING_SNAKE_CASE (for example, HOME_SCREEN). Every Treatment Type defines the surfaces where it can be applied. When your app requests a treatment, it includes the surface identifier, which Auxia uses to determine which treatments are eligible.

{
    "userId": "USER_ID",
    "surfaces": [
        {
            "surface": "HOME_SCREEN",
            "maximumTreatmentCount": 1
        }
    ]
    // ... additional fields — see the Get Treatments API reference for the full request structure
}

Configuration

Surfaces are created and managed in Configuration > UI Layout > Surfaces. This requires admin permissions. Contact your admin to add new surfaces or modify existing ones.

Examples

Surface Name	Typical Use
`HOME_SCREEN`	Welcome messages, featured promotions
`PRODUCT_DETAIL_PAGE`	Upsell, related items, personalized recommendations
`CHECKOUT_PAGE`	Discount offers, cart recovery prompts
`SEARCH_RESULTS`	Sponsored or personalized result callouts
`SETTINGS`	Upgrade prompts, feature discovery

Treatments — treatments are assigned to a surface
Treatment Types — treatment types define which surfaces they can appear on
Destinations — destinations handle delivery for out-of-product channels

How-to guides: Configuration

​Surface Identification and API Usage

​Configuration

​Examples

​Related Concepts

Surface Identification and API Usage

Configuration

Examples

Related Concepts