Skip to main content

Platform Services

Drift provides access to native platform capabilities through the platform package.

Context conventions​

Most platform methods are simple native invocations or native-owned waits where Drift does not expose cancellation.

ctx is reserved for APIs that wait for the user or for file I/O, so ctx cancellation unblocks the Go caller:

  • Permission.Request(ctx) and NotificationPermission.RequestWithOptions(ctx)
  • Storage.PickFile(ctx, ...), Storage.PickDirectory(ctx), Storage.SaveFile(ctx, ...)
  • Storage.ReadFile, WriteFile, DeleteFile and GetFileInfo
  • ShowDatePicker(ctx, ...) and ShowTimePicker(ctx, ...)

When ctx fires on these methods, the Go caller is unblocked promptly with the package's stable error sentinels (ErrCanceled / ErrTimeout for permissions, ctx.Err() for the others). The native operation continues to completion in the background and its result is discarded.

These calls wait, and the reply needs the platform main thread. Go's UI thread (widget callbacks, Build, InitState) is that main thread, so call them from a goroutine and publish the result with drift.Dispatch or a Signal:

go func() {
result, err := platform.Notifications.Permission.Request(ctx)
drift.Dispatch(func() { s.notificationsAllowed = err == nil && result == platform.PermissionGranted })
}()

From the UI thread they fail at once with platform.ErrBlocksUIThread, as plugin methods that reply later do. The DatePicker and TimePicker widgets call their pickers from a goroutine for you.

Clipboard​

Copy and paste text:

import "github.com/go-drift/drift/pkg/platform"

// Copy text to clipboard
err := platform.Clipboard.SetText("Hello, World!")

// Get text from clipboard
text, err := platform.Clipboard.GetText()

// Check if clipboard has text
hasText, err := platform.Clipboard.HasText()

// Clear clipboard
err := platform.Clipboard.Clear()

Example: Copy Button​

// In a Build method with access to ctx:
theme.ButtonOf(ctx, "Copy Link", func() {
platform.Clipboard.SetText(shareURL)
platform.Haptics.LightImpact()
showToast("Link copied!")
})

Haptic Feedback​

Provide tactile feedback to users:

// Light feedback for selections
platform.Haptics.LightImpact()

// Medium feedback for toggles and confirmations
platform.Haptics.MediumImpact()

// Heavy feedback for errors or warnings
platform.Haptics.HeavyImpact()

// Selection change feedback
platform.Haptics.SelectionClick()

// Custom vibration duration (milliseconds)
platform.Haptics.Vibrate(100)

When to Use Haptics​

Feedback TypeUse Case
LightImpactList item selection, minor interactions
MediumImpactToggle switches, button taps
HeavyImpactErrors, deletions, significant actions
SelectionClickPicker value changes, slider movements

App Lifecycle​

App-Level Init and Dispose​

Use OnInit and OnDispose on drift.App to run one-time setup and teardown at the application level, outside the widget tree. OnInit runs in a background goroutine before the root widget is mounted. While it executes, the platform's native splash screen stays visible.

app := drift.NewApp(root)
app.OnInit = func(ctx context.Context) error {
db, err := sql.Open("sqlite3", dbPath)
if err != nil {
return err
}
appDB = db
return nil
}
app.OnDispose = func() {
appDB.Close()
}
app.Run()

If OnInit returns an error, a debug error screen is shown instead of the root widget. The user can tap "Restart" to retry with the normal root widget (OnInit does not re-run on restart).

The ctx passed to OnInit is cancelled before OnDispose runs, so long-running initialization can select on ctx.Done() for clean shutdown:

app.OnInit = func(ctx context.Context) error {
select {
case <-ctx.Done():
return ctx.Err()
case result := <-loadConfig():
return result.Err
}
}
When to use OnInit vs InitState

Use OnInit for work that must complete before any widget mounts: opening databases, loading configuration, restoring authentication tokens. Use InitState in a stateful widget for setup that belongs to a specific screen or component.

Widget-Level Lifecycle Observation​

Respond to app lifecycle state changes using UseLifecycleObserver. The handler is automatically cleaned up when the state is disposed, and always runs on the UI thread via Dispatch:

func (s *myState) InitState() {
platform.UseLifecycleObserver(s, func(state platform.LifecycleState) {
switch state {
case platform.LifecycleStateResumed:
// App came to foreground
s.refreshData()
case platform.LifecycleStatePaused:
// App went to background
s.saveState()
case platform.LifecycleStateInactive:
// App is transitioning (e.g., receiving a phone call)
case platform.LifecycleStateDetached:
// App is detached from any view
}
})
}

For advanced use cases (e.g., subscribing outside a stateful widget), you can use AddHandler and OnDispose manually:

removeHandler := platform.Lifecycle.AddHandler(func(state platform.LifecycleState) {
// handle state change
})
s.OnDispose(removeHandler)

Lifecycle States​

StateDescription
LifecycleStateResumedApp is visible and responding to user input
LifecycleStateInactiveApp is transitioning (system dialog, app switcher)
LifecycleStatePausedApp is not visible but still running
LifecycleStateDetachedApp is detached from any view

Checking Current State​

// Get current state
currentState := platform.Lifecycle.State()

// Convenience methods
if platform.Lifecycle.IsResumed() {
// App is active
}

if platform.Lifecycle.IsPaused() {
// App is in background
}

System UI​

Drift draws edge to edge on both platforms: content extends behind the status bar and navigation bar, so inset it with SafeArea. Choose the status bar's visibility and icon colour to suit the content behind it:

platform.SetSystemUI(platform.SystemUIStyle{
StatusBarHidden: false,
// StatusBarStyleDefault follows the system theme; StatusBarStyleLight
// (light icons) suits dark content, StatusBarStyleDark light content.
StatusBarStyle: platform.StatusBarStyleDark,
})

The style persists until the next call, including across Android Activity recreation (dark mode or locale changes).

Permissions​

Permissions are attached to the features that use them. Each feature service provides a Permission field for checking and requesting access.

Drift owns the request mechanism; the plugin providing a feature registers its permission kind and declares what the platform needs (Android manifest permissions, iOS usage strings). A plugin's runtime package exposes its permissions, built with platform.NewPermission(kind). Calling a permission whose plugin is missing from drift.yaml fails with platform.ErrPermissionNotRegistered; on Android, one whose manifest permission no plugin declares fails with platform.ErrPermissionNotDeclared.

One prompt per permission shows at a time: a Request made while that permission's prompt is up waits for it and returns the same answer.

Notification Permissions​

Drift provides the notification permission, which the notifications and Firebase plugins share; on Android those plugins declare POST_NOTIFICATIONS, and without one of them the permission fails with platform.ErrPermissionNotDeclared. It supports iOS-specific options via RequestWithOptions:

ctx := context.Background()

// Request with default options (Alert, Sound, Badge)
result, err := platform.Notifications.Permission.Request(ctx)

// Request with specific options
result, err := platform.Notifications.Permission.RequestWithOptions(ctx,
platform.NotificationPermissionOptions{
Alert: true,
Sound: true,
Badge: true,
Provisional: false, // iOS provisional notifications
},
)

A RequestWithOptions made while a notification prompt is up returns that prompt's answer; its own options are not used.

Plugin Permissions​

Permissions for features that live in plugins come from those plugins: location from the location plugin, and contacts, calendar, microphone and photos from the permissions plugin. They are platform.Permission values like the ones above.

Up to Drift v0.26, these permissions were fields of core services. Each now comes with its plugin in drift.yaml:

Up to v0.26Now
platform.Location.Permission.WhenInUse, .Alwayslocation.Permission.WhenInUse, location.Permission.Always (github.com/go-drift/drift/plugins/location/runtime); Always needs the plugin's always config
platform.Contacts.Permission, platform.Calendar.Permission, platform.Microphone.Permission, platform.Photos.Permissionpermissions.Contacts, permissions.Calendar, permissions.Microphone, permissions.Photos (github.com/go-drift/drift/plugins/permissions/runtime), each with its section in the plugin's config
platform.Camera.PermissionNone: imagepicker.Capture asks for camera access itself where the platform needs it, and fails with imagepicker.ErrPermissionDenied when denied

Open App Settings​

// Open app settings for manual permission management
platform.OpenAppSettings()

Permission Results​

ResultMeaning
PermissionGrantedPermission was granted
PermissionDeniedPermission was denied (the app may request again)
PermissionPermanentlyDeniedUser selected "Don't ask again"
PermissionRestrictedRestricted by device policy
PermissionLimitedPartial access: selected photos (iOS), approximate location (Android)
PermissionProvisionalProvisional access (iOS notifications)
PermissionNotDeterminedPermission has not been requested yet
PermissionResultUnknownPermission status could not be determined

Camera​

Taking photos and picking images is a plugin: see Image picker in the plugin catalogue.

Up to Drift v0.26 this was platform.Camera. Apps moving to the plugin use its runtime (imagepicker, github.com/go-drift/drift/plugins/imagepicker/runtime):

Up to v0.26Now
CapturePhoto(ctx, platform.CapturePhotoOptions{UseFrontCamera: ...})imagepicker.Capture(ctx, imagepicker.CaptureOptions{FrontCamera: ...}), from a goroutine: the *imagepicker.Image taken, or nil if the user canceled
PickFromGallery(ctx, platform.PickFromGalleryOptions{AllowMultiple: ...})imagepicker.Pick(ctx, imagepicker.PickOptions{Multiple: ...}), from a goroutine: the []imagepicker.Image picked, empty if the user canceled; iOS also picks several
CameraResult (Media, MediaList, Cancelled, Error)The return values above; failures are the returned error
CapturedMediaimagepicker.Image, with the same fields; Width and Height are as displayed. Decode the file with image.Decode from github.com/go-drift/drift/pkg/image
ErrCameraBusyimagepicker.ErrBusy
PermissionSee Plugin Permissions

Location​

Location is a plugin: see Location in the plugin catalogue.

Up to Drift v0.26 this was platform.Location. Apps moving to the plugin use its runtime (location, github.com/go-drift/drift/plugins/location/runtime):

Up to v0.26Now
GetCurrent(platform.LocationOptions{...})location.Current(ctx, location.Options{...}), from a goroutine; returns a location.Update, not a pointer
LastKnown(), IsEnabled()location.LastKnown(ctx), location.IsEnabled(ctx), from a goroutine
StartUpdates(platform.LocationOptions{...})location.SetUpdateOptions(location.UpdateOptions{Options: location.Options{...}}), then listen to location.Updates(): updates run while it has listeners; Background: true keeps them coming in the background
StopUpdates(), Updates()Unsubscribe the last listener of location.Updates()
LocationUpdate, LocationOptionslocation.Update, location.Options, with the same fields
Permission.WhenInUse, Permission.AlwaysSee Plugin Permissions

Notifications​

Local notifications are a plugin: see Notifications in the plugin catalogue; push notifications come from the Firebase plugin. Both use Drift's notification permission.

Up to Drift v0.26, platform.Notifications also scheduled notifications and handled push. Apps moving to the plugins replace those calls with the notifications runtime (notifications, github.com/go-drift/drift/plugins/notifications/runtime) and Firebase messaging (messaging, github.com/go-drift/drift/plugins/firebase/runtime/messaging):

Up to v0.26Now
platform.Notifications.PermissionUnchanged
Schedule(platform.NotificationRequest{...})notifications.Schedule(ctx, notifications.Request{...}), from a goroutine; IntervalSeconds is now Interval, a time.Duration
Cancel(id), CancelAll(), SetBadge(n)notifications.Cancel(id), notifications.CancelAll(), notifications.SetBadge(n)
Settings()notifications.CurrentSettings(ctx), from a goroutine; the permission's status is platform.Notifications.Permission.Status()
Deliveries(), Opens()Local notifications: notifications.Deliveries(), notifications.Opens(). Push: messaging.Messages(), messaging.Opens()
RegisterForPush()Not needed: the Firebase plugin registers at launch
Tokens(), GetPushToken()messaging.Token(), a *core.Derived[string]: Value() reads it, AddListener follows changes
SubscribeToTopic(topic), UnsubscribeFromTopic(topic)messaging.SubscribeToTopic(ctx, topic), messaging.UnsubscribeFromTopic(ctx, topic), from a goroutine
DeletePushToken()messaging.DeleteToken(ctx), from a goroutine
Errors()Each call returns its own error; push registration and token failures are logged natively
NotificationRequest, NotificationEvent, NotificationOpen, NotificationSettingsnotifications.Request, notifications.Notification, notifications.Open, notifications.Settings; push messages and taps are messaging.Message

Background Tasks​

Up to Drift v0.26, platform.Background scheduled background tasks (Schedule, Cancel, CancelAll, CancelByTag, Complete, IsRefreshAvailable, Events). It is removed, with no replacement: it never ran the app's Go code in the background.

Share​

Open the native share sheet:

// Share text
result, err := platform.Share.ShareText("Check out this app!")

// Share text with subject (for email)
result, err := platform.Share.ShareTextWithSubject("Check out this!", "App Recommendation")

// Share a URL
result, err := platform.Share.ShareURL("https://example.com")

// Share URL with text
result, err := platform.Share.ShareURLWithText("https://example.com", "Check out this link!")

// Share a file
result, err := platform.Share.ShareFile("/path/to/file.pdf", "application/pdf")

URL Launcher​

Open URLs in the system browser or check whether the device can handle a given URL scheme:

import "github.com/go-drift/drift/pkg/platform"

// Open a URL in the system browser
err := platform.URLLauncher.OpenURL("https://example.com")

// Check if the system can open a URL
canOpen, err := platform.URLLauncher.CanOpenURL("https://example.com")

// Open other URL schemes
platform.URLLauncher.OpenURL("mailto:hello@example.com")
platform.URLLauncher.OpenURL("tel:+1234567890")
theme.ButtonOf(ctx, "Visit Website", func() {
if err := platform.URLLauncher.OpenURL("https://example.com"); err != nil {
showToast("Could not open link")
}
})

Supported Schemes​

Both platform templates include http, https, mailto, tel, and sms by default. To query or open custom URL schemes, update the platform manifests:

  • iOS: Add schemes to LSApplicationQueriesSchemes in Info.plist
  • Android: Add schemes to the <queries> block in AndroidManifest.xml
note

CanOpenURL only reports schemes declared in the app's manifest. URLs with undeclared schemes return false even if another app on the device can handle them.

File Storage​

Access files and directories. Paths may be content URIs on Android (what the pickers return). Every call except GetAppDirectory waits for file I/O off the main thread, so call them from a goroutine:

go func() {
// Read a file
data, err := platform.Storage.ReadFile(ctx, "/path/to/file.txt")

// Write a file
err = platform.Storage.WriteFile(ctx, "/path/to/file.txt", []byte("content"))

// Delete a file
err = platform.Storage.DeleteFile(ctx, "/path/to/file.txt")

// Get file info
info, err := platform.Storage.GetFileInfo(ctx, "/path/to/file.txt")
}()

// Get app directory (does not wait; any thread)
docsPath, err := platform.Storage.GetAppDirectory(platform.AppDirectoryDocuments)
cachePath, err := platform.Storage.GetAppDirectory(platform.AppDirectoryCache)

File Picker​

The pickers return nothing (no files, an empty path, no error) when the user cancels, and platform.ErrStorageBusy if a picker is already open.

go func() {
files, err := platform.Storage.PickFile(context.Background(), platform.PickFileOptions{
AllowMultiple: false,
AllowedTypes: []string{"image/*", "application/pdf"},
})
drift.Dispatch(func() {
if err != nil {
handleError(err)
return
}
for _, file := range files { // none if canceled
handleSelectedFile(file)
}
})
}()

PickDirectory(ctx) returns the chosen directory and SaveFile(ctx, data, opts) the saved file, each "" if canceled.

Preferences​

Store simple, unencrypted key-value data using platform-native storage (UserDefaults on iOS, SharedPreferences on Android). For sensitive data, use secure storage instead.

import "github.com/go-drift/drift/pkg/platform"

// Store a value
err := platform.Preferences.Set("username", "alice")

// Retrieve a value
username, err := platform.Preferences.Get("username")

// Check if a key exists (useful to distinguish missing keys from empty values)
exists, err := platform.Preferences.Contains("username")

// Delete a value
err = platform.Preferences.Delete("username")

// List all keys
keys, err := platform.Preferences.GetAllKeys()

// Delete all stored values
err = platform.Preferences.DeleteAll()

Secure Storage​

Encrypted storage, with optional biometric protection, is a plugin: see Secure storage in the plugin catalogue. For values that need no protection, use Preferences.

Up to Drift v0.26 this was platform.SecureStorage. Apps moving to the plugin use its runtime (securestorage, github.com/go-drift/drift/plugins/securestorage/runtime). Every call now takes a ctx and waits for the platform, so call them from a goroutine:

Up to v0.26Now
Set(key, value, opts)securestorage.Set(ctx, key, value, opts)
Get(key, opts): "" for a missing keysecurestorage.Get(ctx, key, opts): the value and whether there is one
Delete, Contains, DeleteAllsecurestorage.Delete, securestorage.Contains, securestorage.DeleteAll, each with ctx first
GetAllKeys(opts)securestorage.Keys(ctx, opts)
GetBiometricType(), IsBiometricAvailable()securestorage.AvailableBiometric(ctx); none available is securestorage.BiometricNone
ErrAuthPending, Listen()Removed: Get waits for the biometric prompt and returns its result
SecureStorageError codes auth_failed, auth_cancelled, biometric_not_available, biometric_not_enrolledsecurestorage.ErrAuthFailed, securestorage.ErrAuthCanceled, securestorage.ErrBiometricsUnavailable (both of the last two), under errors.Is
ErrPlatformNotSupportedRemoved: every Android version Drift supports has secure storage
SecureStorageOptions{KeychainAccessibility, RequireBiometric, BiometricPrompt, Service}securestorage.Options{Accessibility, RequireBiometric, BiometricPrompt, Service}; RequireBiometric needs the plugin's biometrics config
KeychainAccessibility (AccessibleWhenUnlocked, ...)securestorage.Accessibility (securestorage.WhenUnlocked, AfterFirstUnlock, WhenUnlockedThisDeviceOnly, AfterFirstUnlockThisDeviceOnly)
BiometricType (BiometricTypeFaceID, ...)securestorage.Biometric (securestorage.BiometricFaceID, BiometricTouchID, BiometricFingerprint, BiometricFace, BiometricNone; also BiometricOpticID)

On Android the plugin keeps its values in files of its own, so values platform.SecureStorage stored there are not read; iOS reads them as before.

Thread Safety​

Platform services are safe to call from any goroutine, but calls that wait for the user must not run on the UI thread (see Context conventions). When updating UI state from platform callbacks, use drift.Dispatch:

unsubscribe := platform.DeepLinks.Links().Listen(platform.StreamHandler[platform.DeepLink]{OnEvent: func(link platform.DeepLink) {
// Called from background goroutine
drift.Dispatch(func() {
// Now safe to update UI
s.lastLink = link
})
}})
defer unsubscribe()

Next Steps​