Overview

If your app uses SwiftUI, follow the steps in this guide. You add two modifiers to your views:

.hanselScreen("...") names a screen.
.hanselIndex("...") names an element that a nudge can point at.

Neither modifier changes how your UI looks or behaves. Once you name your screens and elements, your team can create and update nudges from the portal without shipping a new build.

Note
SwiftUI support is available from SDK version 9.0.39 onwards.

Prerequisites

Add import SmartechNudges at the top of every SwiftUI file that uses the modifiers.

// At the top of the file
import SwiftUI
import SmartechNudges

Requires iOS 13 or later
On older iOS versions, the code still compiles, but nudges do not appear.

Step 1: Set hanselScreen

Add .hanselScreen("...") to the outermost view of each screen. Use a unique screen name.

struct HomeView: View {
    var body: some View {
        VStack {
            Text("Welcome back")
            Button("Upgrade") { }
        }
        .hanselScreen("home")
    }
}

Required
Nudges appear only on screens that have a screen name.

Step 2: Set hanselIndex

Add .hanselIndex("...") to each element that a nudge can point at. Use a unique name for each element.

VStack(spacing: 20) {

    Text("Current plan: Free")
        .hanselIndex("home_plan_label")

    Button("Upgrade to Pro") { }
        .hanselIndex("home_upgrade_button")

    Image(systemName: "bell")
        .hanselIndex("home_notification_icon")
}
.hanselScreen("home")

Lists and scrolling content

In a List or ForEach, include the row's id in the name. This keeps every row unique.

List(offers) { offer in
    HStack {
        Text(offer.title)
            .hanselIndex("offer_title_\(offer.id)")

        Spacer()

        Button("Claim") { }
            .hanselIndex("offer_claim_\(offer.id)")
    }
    .hanselIndex("offer_row_\(offer.id)")
}
.hanselScreen("offers")

Never use the same name on two rows
The SDK cannot tell rows that share a name apart, so the nudge does not appear.

A complete screen, start to finish

This example combines all of the above in one file.

import SwiftUI
import SmartechNudges
import Smartech

struct HomeView: View {

    var body: some View {
        NavigationView {
            VStack(spacing: 24) {

                Text("Current plan: Free")
                    .font(.headline)
                    .hanselIndex("home_plan_label")

                Button("Upgrade to Pro") {
                    Smartech.sharedInstance().trackEvent("Upgrade Tapped", andPayload: nil)
                }
                .hanselIndex("home_upgrade_button")

                HStack(spacing: 30) {
                    Image(systemName: "bell")
                        .hanselIndex("home_notification_icon")

                    Image(systemName: "gearshape")
                        .hanselIndex("home_settings_icon")
                }

                Spacer()
            }
            .padding()
            .navigationTitle("Home")
        }
        .hanselScreen("home")
    }
}

Rules for names

Live nudges look for these exact names. Treat them as permanent.

Rule	Why it matters
Unique on the screen	The SDK cannot tell duplicate names apart.
Keep it stable across releases	Renaming breaks live nudges.
Lowercase with underscores	This format is easy to read, for example `cart_checkout_button`.
No comma or semicolon	The SDK reserves these characters.
Describe the element, not the design	`home_upgrade_button` survives a redesign. `blue_button_2` does not.

Dos and don'ts

Add .hanselScreen() to every screen.
Mark generously. Extra names cost nothing.
Include the row id on list items.
Keep names the same in future releases.
Send us the list of names you used.

Don't

Reuse a name on two elements.
Rename an element that a live nudge already uses.
Put the name on the inner Text of a button. Put it on the button.
Skip the screen name and expect nudges to work.
Add commas or semicolons to names.

Troubleshooting

What you see	Most likely cause	What to do
Xcode: no such module 'SmartechNudges'	The SDK is not linked to this target.	Contact us to check the integration.
Xcode: value of type ... has no member 'hanselIndex'	`import SmartechNudges` is missing.	Add the import at the top of the file.
No nudge appears anywhere on a screen	The screen has no `.hanselScreen()`.	Add it to the outermost view.
Nudge appears on some rows but not others	Two rows share a name.	Include the row's id in the name.
You cannot select an element when you set up a nudge	The element has no `.hanselIndex()`, or the row was not on screen during capture.	Add the name, scroll the row into view, and capture again.
Nudge shows on the wrong screen	Two screens share a name.	Give each screen its own name.

For integration or SDK questions, contact your Netcore account manager.