Selections
A selection is a natively-stored set of app/category/web-domain tokens,
created by the <ActivityPicker /> and
addressed everywhere by a selectionId string. These utilities manage stored
selections. All are named exports and also live on the default export, and
work the same on both platforms (the Android notes below cover
what differs underneath).
Inspecting
listSelections(): Promise<string[]>
All persisted selection IDs.
hasSelection(selectionId: string): Promise<boolean>
Whether a selection exists under that ID.
getSelectionMetadata(selectionId: string): Promise<SelectionMetadata | null>
Counts only — no token data.
const meta = await getSelectionMetadata('my-blocklist');
// { applicationCount: 12, categoryCount: 2, webDomainCount: 0 }getTokens(selectionId: string): Promise<TokenHandle[] | null>
Opaque token handles for a selection — pass them to
token labels to render app/category names, or to
removeToken. Call this on app restart to restore handles from the native store.
const tokens = await getTokens('my-blocklist');
// [{ handle: '…', type: 'application' }, { handle: '…', type: 'category' }]removeToken(selectionId: string, handle: string): Promise<void>
Remove a single token from a selection by its handle.
deleteSelection(selectionId: string): Promise<void>
Delete the stored selection.
Set operations
mergeSelections(targetId: string, sourceIds: string[]): Promise<void>
Union of the sources, saved under targetId.
keepCommonSelections(targetId: string, sourceIds: string[]): Promise<void>
Intersection of the sources, saved under targetId.
subtractSelection(targetId: string, fromId: string, subtractId: string): Promise<void>
fromId minus subtractId, saved under targetId.
await mergeSelections('all-distractions', ['social', 'games']);
await subtractSelection('weekday-blocklist', 'all-distractions', 'work-tools');Export / Import
exportSelection(selectionId: string): Promise<string | null>
Export a selection as an opaque string for backup.
Device-bound
Tokens are device-specific and tied to the user's iCloud account; the Android blob is bound to the install the same way. An exported selection only imports back on the same device/account — this is not a cross-device sync mechanism. Treat the string as an opaque blob.
importSelection(selectionId: string, data: string): Promise<boolean>
Import a previously exported selection. Returns false, and leaves the
selection as it was, if the data doesn't decode to a valid selection: a
malformed string, a blob made on the other platform (an iOS blob on Android
and the reverse — no mapping between tokens and packages exists), or an
Android blob from another install.
Android
The same functions, over package names instead of tokens, kept native:
- Apps only.
getCapabilities().selectableKindsreportsapplications: true,categories: false,webDomains: false, socategoryCountandwebDomainCountare always0and every handle hastype: 'application'. - Handles are salted per install. A handle is derived from the package
name and a random secret the library draws once per install, so it is
stable across launches (persist it, pass it to
removeTokenor a label) but never an encoding of the package name, and meaningless on another install. JS cannot learn a package name from a handle, nor build a handle for a package it names. - Export blobs are encrypted under a key derived from that secret and tagged as Android blobs. They restore on the same install (the counterpart of iOS's same-device/account rule) and never show a package name.
- The store is shared with the enforcement engine, which runs in its own process: a selection written by the picker is what the engine will block when blocking lands on Android.