iOS Guide

The Spam Control SDK blocks and identifies spam calls through Apple’s Call Directory Extensions. Everything goes through SpamControl.shared. Current version: 3.0.0.

iOS 14 or later. Releases are built with Xcode 16.4 and import in apps on Xcode 16 or 26.
Test on a physical device: call blocking does not run on the Simulator.
Phone numbers are Brazilian, 55 + area code + number (e.g. 5511987654321).

Setup

1. Add the framework

Add FeatureSpamControl.xcframework (provided by Bemobi) as Embed & Sign in the app and as Do Not Embed in each extension. Every slice carries its own PrivacyManifest.xcprivacy, declaring the data the SDK collects and the APIs it uses. Your app still declares its own.

2. Create the extensions and App Groups

Create one Call Directory Extension target per feature. Their bundle identifiers must start with the app’s.

Extension	Type	Handler
Spam blocking	`.blockSpams`	`WaveCallDatasetDirectoryHandler`	Required
Identification	`.callIdentifier`	`WaveCallIdentificationHandler`	Optional, labels spam calls
Manual blocking	`.blockManual`	`WaveCallUserDirectoryHandler`	Optional, numbers the user blocks

Add the App Groups capability to the app and to each extension. Spam blocking and identification must share one App Group, where the database lives. Manual blocking can use the same group or its own. Use the same identifiers everywhere below.

3. Implement the extension handlers

Spam blocking and identification complete the request in a callback:

import CallKit
import FeatureSpamControl

final class CallDirectoryHandler: CXCallDirectoryProvider, CXCallDirectoryExtensionContextDelegate {

    private let directory = WaveCallDatasetDirectoryHandler(appGroup: "group.your.app.spam")
    // Identification: WaveCallIdentificationHandler(appGroup: "group.your.app.spam", hintIdentifier: "Possible spam")

    override func beginRequest(with context: CXCallDirectoryExtensionContext) {
        context.delegate = self
        directory.beginRequest(with: context) { result in
            switch result {
            case .success: context.completeRequest()
            case .failure(let error): context.cancelRequest(withError: error)
            }
        }
    }

    func requestFailed(for extensionContext: CXCallDirectoryExtensionContext, withError error: Error) {
        directory.requestFailed(for: extensionContext, withError: error)
    }
}

Manual blocking is synchronous and throws:

private let directory = WaveCallUserDirectoryHandler(appGroup: "group.your.app.manual", hintIdentifier: "Blocked by you")

override func beginRequest(with context: CXCallDirectoryExtensionContext) {
    context.delegate = self
    do {
        try directory.beginRequest(with: context)
        context.completeRequest()
    } catch {
        context.cancelRequest(withError: error)
    }
}

hintIdentifier is the label iOS shows on the call. Each handler also has a failable initializer without appGroup: that reads the SpamControlAppGroup key from the extension’s Info.plist. Manual blocking never blocks one of the user’s contacts: the SDK asks for contacts access on the first manual block, so add NSContactsUsageDescription to the app’s Info.plist.

4. On every launch

In application(_:didFinishLaunchingWithOptions:), or in your SwiftUI App’s init, register the extensions and then call refresh(). Both are required on every launch. Never call the SDK from the extensions.

SpamControlConfiguration.shared.configureExtensions(with: [
    ExtensionBlockModel(appGroup: "group.your.app.spam", bundleIdentifier: "com.yourcompany.app.SpamBlocking", extensionType: .blockSpams),
    ExtensionBlockModel(appGroup: "group.your.app.spam", bundleIdentifier: "com.yourcompany.app.SpamIdentification", extensionType: .callIdentifier),
    ExtensionBlockModel(appGroup: "group.your.app.manual", bundleIdentifier: "com.yourcompany.app.ManualBlocking", extensionType: .blockManual)
])
Task(priority: .utility) { await SpamControl.shared.refresh() }

refresh() keeps the SDK up to date and starts its automatic refresh, see Refresh.

Declaring the extensions in the Info.plist

Instead of configureExtensions(with:), declare them in the app’s Info.plist under SpamControlExtensions:

<key>SpamControlExtensions</key>
<array>
    <dict>
        <key>Type</key><string>blockSpams</string>
        <key>BundleIdentifier</key><string>com.yourcompany.app.SpamBlocking</string>
        <key>AppGroup</key><string>group.your.app.spam</string>
    </dict>
    <dict>
        <key>Type</key><string>callIdentifier</string>
        <key>BundleIdentifier</key><string>com.yourcompany.app.SpamIdentification</string>
        <key>AppGroup</key><string>group.your.app.spam</string>
    </dict>
</array>

Type is blockSpams, callIdentifier or blockManual; an entry missing a key is ignored. The code call wins when both exist. This replaces only configureExtensions(with:): refresh() is still required on every launch.

Activation

The user first turns the extensions on in Settings > Apps > Phone > Call Blocking & Identification (Settings > Phone before iOS 18); openSettings() opens Settings. Then call enable once:

let result = await SpamControl.shared.enable(
    apiKey: apiKey,               // provided by Bemobi; differs between stage and production
    phoneNumber: "5511987654321",
    environment: .production,     // or .stage
    subscriptionMode: .free       // or .paid, see Subscription mode
)

switch result {
case .success, .alreadyOn:
    break
case .extensionsDisabled(let types):
    // `types` are the extensions still off in Settings
    try? await SpamControl.shared.openSettings()
case .failed(let reason, _):
    showError(for: reason) // see Failure reasons
}

enable downloads and applies the whole database, so it can take a few seconds. It saves the credentials, so later launches don’t need them.

Result	Meaning
`.success`	The SDK is on.
`.alreadyOn`	It was already on. Nothing changed.
`.extensionsDisabled([types])`	These configured extensions are off in Settings. The SDK stays off.
`.failed(reason:underlying:)`	The SDK stays off. See Failure reasons.

To switch account, environment or mode, call disable() and then enable again.

State and deactivation

isEnabled tells whether the SDK is on. Re-read it when your screen appears, because the SDK turns itself off when the user turns the spam blocking extension off in Settings, or when the subscription is cancelled. Call enable again to turn it back on. disable() turns the SDK off until the next enable, across launches. Manually blocked numbers and category choices are kept.

Refresh

After the first refresh(), the SDK also refreshes whenever the app returns to the foreground. A refresh downloads the database at most once every 24 hours and applies it, together with the subscription state. Pass force: true only on an explicit user action, to ignore the 24-hour window. refresh never throws, the result is discardable, and calling it again while one is running is safe.

Outcome	Meaning
`.updated`	A new database was downloaded and applied.
`.upToDate`	Nothing to do.
`.disabled`	The SDK is off: never activated, `disable()` called, subscription cancelled, or the user turned the spam blocking extension off in Settings, which turns the SDK off.
`.failed(reason:underlying:)`	The next refresh resumes. See Failure reasons.

Failure reasons

EnableResult.FailureReason and SpamDatabaseRefreshOutcome.FailureReason are separate enums with overlapping cases, so a switch over one does not accept the other.

Reason	Meaning
`.network`	Network or server failure. Try again later.
`.authentication`	The credentials were rejected.
`.extensionDisabled`	An extension, e.g. identification, is off in Settings. Retrying does not help: take the user to Settings (`refresh` only).
`.extensionReloadFailed`	iOS failed to reload an extension. Usually transient.
`.database`	The local database could not be saved or opened.
`.configuration`	Missing `.blockSpams` configuration, credentials or App Group.
`.emptyApiKey`, `.emptyPhoneNumber`	Empty `enable` argument (`enable` only).
`.unsupportedEnvironment`	Not supported here, e.g. on the Simulator.
`.unknown`	Could not be classified.

Subscription mode

State	`.paid`	`.free` (default)
`active`, `pendingCancelation`	blocks normally	ignored
`pendingPayment`	suspends blocking; identification keeps running	ignored
`cancelled`	turns the SDK off	ignored
`subscriptionRequired`	turns the SDK off	turns the SDK off

The mode is set at activation and ignored by an enable on an SDK already on: to change it, disable() first. subscriptionMode returns the mode in force, saved across launches. The state comes with the daily database download, so right after enable there is none yet. To apply a change sooner, call refreshSubscriptionState() when the user opens your Spam Control screen; it returns nil in .free mode. subscriptionState() reads the last known state locally, e.g. to show pending-payment UI. cancelSubscription(reason:) throws if the request fails, e.g. when the backend has no subscription for the number.

API reference

Everything is on SpamControl.shared, except the last two rows.

Method	Signature	Description
`enable(apiKey:phoneNumber:environment:subscriptionMode:)`	`async -> EnableResult`	Turns the SDK on. See Activation.
`refresh(force:)`	`async -> SpamDatabaseRefreshOutcome`	Required on every launch, then automatic. See Refresh.
`disable()`	`async throws`	Turns the SDK off until the next `enable`.
`isEnabled`	`Bool`	Whether the SDK is on.
`subscriptionMode`	`SubscriptionMode`	The mode in force.
`subscriptionState()`	`-> SubscriptionState?`	The last known state, read locally.
`refreshSubscriptionState()`	`async -> SubscriptionState?`	Fetches and applies the state. `nil` in `.free` mode or without information.
`cancelSubscription(reason:)`	`async throws`	Cancels the subscription. The reason is optional.
`isCallDatasetDirectoryEnabled()`, `isCallIdentificationDirectoryEnabled()`	`async -> Bool`	Whether that extension is on in Settings.
`isCallUserDirectoryEnabled()`, `areAllExtensionsEnabled()`	`async throws -> Bool`	Whether the manual extension, or all three, are on in Settings.
`openSettings()`	`async throws`	Opens iOS Settings. Some iOS versions stop at Phone.
`categories()`	`async -> [SpamCategory]`	The spam categories with the user’s choices, read locally. Empty before the first download.
`toggleCategoryBlockState(categoryId:)`	`async throws -> [SpamCategory]`	Blocks or unblocks one category, and returns them all.
`blockUserPhoneNumber(phoneNumber:)`, `unblockPhoneNumber(phoneNumber:)`	`async throws -> [Int64]`	Manual blocking. Returns the resulting block list. Throws `BlockManuallyErrorType`.
`retrievedBlockedUserPhoneNumbers()`	`-> [CXCallDirectoryPhoneNumber]`	The numbers the user blocked.
`addTrustedNumber(_:)`, `removeTrustedNumber(_:)`	`async throws`	Numbers that are never blocked. Throws `TrustedNumbersErrorType`.
`getTrustedNumbers()`	`async -> [String]`	The trusted numbers.
`totalBlockedCalls()`	`async throws -> TotalBlockedCalls?`	Blocked calls, from the server.
`totalPhoneNumbersAtDatabase()`	`async throws -> Int?`	Numbers in the local database. Throws before the first download.
`SpamControlConfiguration.shared.configureExtensions(with:)`	`([ExtensionBlockModel])`	Registers the extensions. See On every launch.
`SpamControlConfiguration.shared.getSDKEnviroment()`	`throws -> SDKEnviroment`	The saved environment. Throws before the first `enable`; apps updated from 2.x report `.production` until then.

A number is either blocked by the user or trusted: the latest action wins. Removing a trusted number puts it back where it came from.

Types

public struct SpamCategory { public let id: Int; public let category: String; public let description: String; public var isBlocked: Bool }
public struct TotalBlockedCalls { public let name: String; public let value: Int }
public struct ExtensionBlockModel { public init(appGroup: String, bundleIdentifier: String, extensionType: ExtensionType) }
public enum SDKEnviroment: String { case production = "PRODUCTION", stage = "STAGE" }
public enum SubscriptionMode: String { case free, paid }
public enum SubscriptionState: String, CaseIterable { case active, pendingPayment, cancelled, pendingCancelation, subscriptionRequired }

CXCallDirectoryPhoneNumber is CallKit’s typealias for Int64. BlockManuallyErrorType cases you are most likely to handle: phoneNumberAlreadyBlocked, phoneNumberNotBlocked, phoneNumberInContacts, invalidPhoneNumberFormat, emptyPhoneNumber, phoneNumberInsufficientSignificantDigits, permissionDenied (contacts), callDirectoryIsNotEnabled and networkUnavailable; it has more cases, and most carry associated values with the number and the context. TrustedNumbersErrorType covers an invalid number, a disabled extension and storage or database failures. Both are LocalizedError.

Migrating from 2.x

Keep configureExtensions(with:) on every launch, or move it to the Info.plist.
Add refresh() on every launch, right after it.
Replace the 2.x calls:

2.x	3.x
`setup(...)`, `downloadFullDatabase()`, `applySpamPhoneNumberBlocking()`, `applyIdentificationSpamPhoneNumberBlocking()`, `Wave.shared.setup(...)`	`enable(...)` when the user turns the protection on
`disabledSDK()`	`disable()`
`downloadSpamCategories(cacheValidityDuration:)`	`categories()`
`blockSpamPhoneNumberByCategories(for:)`	`toggleCategoryBlockState(categoryId:)`
`blockUserPhoneNumbers(_:)`	`blockUserPhoneNumber(phoneNumber:)` per number
`getSubscriptionInfo()`	`refreshSubscriptionState()` and `subscriptionState()`
`Wave`, `CallDirectoryExtension*`, top-level `ExtensionType`	`configureExtensions(with:)` and `ExtensionBlockModel.ExtensionType`
`downloadWithCellularDataEnabled`, `isNetworkConnected`, `isOnWiFi`, `stopNetworkMonitoring()`, `getUserContacts()`, `StatisticsSDKModel`, `getAppGroupIdentifier(for:)`, `getBundleIdentifierExtension(with:)`	Removed

Keep the App Group of .blockSpams, where your users’ database is. If identification used its own group, move it into the .blockSpams group, not the other way round.

Users activated with 2.x keep blocking after the update without calling enable. Calling it later is optional: it returns .alreadyOn and only saves the values it receives, e.g. to switch those users to .paid.

SDK Documentation

Activation SDK

Usage SDK

Spam Control SDK

Offers SDK

Setup

1. Add the framework

2. Create the extensions and App Groups

3. Implement the extension handlers

4. On every launch

Declaring the extensions in the Info.plist

Activation

State and deactivation

Refresh

Failure reasons

Subscription mode

API reference

Types

Migrating from 2.x

​Setup

​1. Add the framework

​2. Create the extensions and App Groups

​3. Implement the extension handlers

​4. On every launch

​Declaring the extensions in the Info.plist

​Activation

​State and deactivation

​Refresh

​Failure reasons

​Subscription mode

​API reference

​Types

​Migrating from 2.x

Setup

1. Add the framework

2. Create the extensions and App Groups

3. Implement the extension handlers

4. On every launch

Declaring the extensions in the Info.plist

Activation

State and deactivation

Refresh

Failure reasons

Subscription mode

API reference

Types

Migrating from 2.x