Skip to main content

iOS Native SDK

The PulpoAR iOS SDK brings the virtual try-on into your iOS app natively, with no WebView. It shows your project's catalog and Studio theme, and runs the camera and makeup natively.

Before you start
  • The SDK is proprietary and needs an agreement with PulpoAR.
  • You need your project slug from PulpoAR Studio. The SDK uses it to load your catalog and theme.
  • Runnable example apps are in pulpoar-plugin-examples.

Choose a module​

ModuleImportUse it when
PulpoTryOnUI (recommended)import PulpoTryOnUIYou want the complete try-on (live camera, photo, models, products, looks, before/after), styled with your Studio theme. One view, no try-on code. Includes PulpoTryOnKit.
PulpoTryOnKitimport PulpoTryOnKitYou design your own screens. The Kit gives you the camera view, catalog and makeup, without UI.
PulpoModule–The underlying makeup engine. Linked automatically by both modules above.

Requirements​

  • Xcode 26 or later
  • iOS 15.6 or later
  • A physical iPhone to test the camera (the simulator has no camera)
Simulator

The frameworks include an arm64 device slice and an x86_64 simulator slice only. There's no arm64 simulator slice yet.

1. Add the package​

Xcode: choose File → Add Package Dependencies…, enter https://github.com/pulpoar/pulpoar-ios-sdk, choose Up to Next Major Version from 0.1.0, and add PulpoTryOnUI to your app target.

Package.swift:

dependencies: [
.package(url: "https://github.com/pulpoar/pulpoar-ios-sdk", from: "0.1.0")
],
targets: [
.target(name: "YourApp", dependencies: [
.product(name: "PulpoTryOnUI", package: "pulpoar-ios-sdk") // or "PulpoTryOnKit"
])
]

To update later, choose File → Packages → Update to Latest Package Versions (or run swift package update).

2. Allow the camera​

In your target's Info tab, add Privacy - Camera Usage Description (NSCameraUsageDescription). For example: "The camera shows you wearing the products."

Photo upload uses the system picker and needs no permission.

3. Configure once​

Configure the SDK once when your app starts, before any try-on is shown:

import PulpoTryOnKit

PulpoTryOn.configure(PulpoTryOnConfiguration(analyticsConsent: .pending))

Nothing is reported while consent is .pending. When the user answers your consent prompt, pass their answer:

PulpoTryOn.analyticsConsent = userAccepted ? .granted : .denied

If your app already knows the answer at launch, pass it to configure instead.

warning

Never pass .granted without the user's consent.

4. Show the try-on​

SwiftUI​

import PulpoTryOnKit
import PulpoTryOnUI
import SwiftUI

@main
struct MyApp: App {
init() {
PulpoTryOn.configure(PulpoTryOnConfiguration(analyticsConsent: .pending))
}

var body: some Scene {
WindowGroup {
PulpoTryOnView(projectSlug: "your-project", configuration: .init(
onAddToCart: { variants in /* add to your cart */ },
onClose: { /* dismiss the try-on */ }
))
}
}
}

UIKit​

let tryOn = PulpoTryOnViewController(projectSlug: "your-project", configuration: .init(
onClose: { [weak self] in self?.dismiss(animated: true) }
))
tryOn.modalPresentationStyle = .fullScreen
present(tryOn, animated: true)

5. Connect it to your app​

All configuration options are optional:

PulpoTryOnView(projectSlug: "your-project", configuration: .init(
onAddToCart: { variants in cart.add(variants) }, // without it, Add to Cart opens the product's web page
onGoToProduct: { variant in openProductPage(variant) }, // the Details button
onClose: { isTryOnPresented = false }, // the close button; dismiss the try-on here
customizeTheme: { theme in
theme.catalog.withAddToCart = true // override anything in your Studio theme
}
))
OptionDescription
onAddToCartCalled with the selected variants when Add to Cart is tapped. Without it, Add to Cart opens the product's web page.
onGoToProductCalled when the Details button is tapped.
onCloseCalled when the close button is tapped. Dismiss the try-on here.
customizeThemeChanges any value of your Studio theme in code.
initialSelectionOpens on a product (.product("product-slug")), shades (.variants(["variant-slug"])) or a look (.look("look-id")).
localeForces a language: en, tr, pt, it, fr or ru. Otherwise it follows the theme and the device.

The try-on fills the space you give it and picks its layout from that size:

LayoutWhenWhat users see
Phone layoutThe view is taller than it is wideCamera or photo on top, catalog as a panel at the bottom
Wide layoutThe view is wider than it is tall, or at least 700 pt wide (iPad)Camera or photo on the left (45%), catalog as a side panel on the right (55%)
  • Best: full screen, or a full-height sheet (the .large detent).
  • On phones, keep it taller than it is wide. Avoid half-height sheets. If the sheet ends up wider than it is tall, the try-on switches to the wide layout, which is cramped at that size.
  • Keep the image area at least 520 pt tall. Below that (landscape, small phones, short sheets), the controls switch to a compact version.

Building your own UI with the Kit​

Add PulpoTryOnKit instead of PulpoTryOnUI. A session owns the camera, catalog and makeup. A camera view shows the result.

import PulpoTryOnKit
import SwiftUI

struct MyTryOnScreen: View {
@StateObject private var session = PulpoTryOnSession(projectSlug: "your-project")

var body: some View {
PulpoCameraView(session: session)
.task {
do {
try await session.start(.camera(position: .front))
if let variant = session.catalog?.variants.first {
_ = try await session.apply([variant])
}
} catch {
// PulpoError: camera denied, no network, unsupported device…
}
}
.onDisappear { Task { await session.stop() } }
}
}

You build the catalog UI from session.catalog and apply variants with session.apply(_:).

Good to know​

  • Hidden and shown again: when the try-on is in a tab you leave, or covered by another screen, it releases the camera and comes back where it was.
  • Landscape: supported, with the catalog on the right. Lock your app to portrait if you prefer.
  • One try-on at a time: the engine is shared, so only the visible try-on uses it.

Standalone try-on app​

If you want an app that's only the try-on, under your own name and icon, start from the Try-On UI example. Replace the shop screens with a single PulpoTryOnView, set your project slug, name and icon, and publish. PulpoAR can also prepare a branded try-on app for you. Contact your PulpoAR representative.

Resources​