Docs

iOS SDK

The Hlpd Swift package adds the help centre, walkthroughs, support chat and ticket screens to a SwiftUI app.

Requirements

• iOS 17. The portable core also builds for macOS 14.
• A help bundle from the generator, and an SDK key and public project id from the admin.

Install

1. Add sdk/ios/Hlpd from the hlpd repository to your project as a Swift package dependency.
2. Add the generated bundle directory to the app target as a folder reference named HlpdBundle.

Configure

import Hlpd

let hlpd = HlpdConfiguration(
    apiKey: "hk_...",                                  // the project's SDK key
    tickets: HlpdTickets(serverURL: URL(string: "https://api.hlpd.uk")!,
                         projectID: "brp_..."),        // the project's public id
    context: { ["screen_name": "Settings"] }
)

baseURL defaults to https://api.hlpd.uk. context returns the current screen name and any app state that helps answer a question. It is added to the chat prompt for each question and attached to ticket metadata.

Show help and support

HelpCenterView(configuration: hlpd)                         // help centre, search, chat, contact support
HelpSupportView(configuration: hlpd)                        // ticket inbox, report composer, threads
HelpSuggestionsView(text: $reportText, configuration: hlpd) // help shown above your own report form

The help centre searches on the device with BM25 plus a static embedding model, and offers Show me and Guide me for topics that have a walkthrough.

Escalation

When the chat cannot answer from your help topics, it offers to send the question to support. The user can edit the ticket title and summary before anything is sent, and the ticket then appears in the chat as a card that opens its thread.

If you leave out tickets, escalations go to onEscalate with no ticket id and the chat says support is handled by the app, so your own support flow can take over.

Suggestions above your own form

HelpSuggestionsView(text:configuration:) takes the text the user is typing in your bug report or contact form. Once the text has three content words it waits 400 ms, then shows up to three "This might help" cards that clear the bundle's suggestion thresholds. Opening a card shows the topic and its walkthroughs without losing the draft.

Device id

The SDK generates one 16-character base62 device id per install and keeps it in UserDefaults under Hlpd.deviceID (HlpdDeviceIDStore). Help requests send it as X-Hlpd-Device and bug reports send it as client_id, so the server links a device's reports and help activity.

Bug reports without the help centre

BugReporter submits reports and feature requests to POST /api/reports, tracks the user's tickets and replies, and registers APNs tokens for reply pushes. BugReportSupportView, or the .bugReportSupportSheet(isPresented:reporter:) modifier, is a ready-made report list, composer and thread screen:

let reporter = BugReporter(serverURL: URL(string: "https://api.hlpd.uk")!, projectID: "brp_...")

Button("Support") { showsSupport = true }
    .bugReportSupportSheet(isPresented: $showsSupport, reporter: reporter)

For a custom interface, prepare(title:body:kind:...) returns a pending report whose reportDetails and metadataDetails can be shown to the user before approved() and submit(_:).