iOS step 2: add the extension

About two hours. Every step happens in Xcode.

Finish iOS prerequisites first. You need your App IDs registered before Xcode can sign anything.

What you are building

Your app gets a second target: a small extension that iOS loads during an incoming call. The extension code is six lines. The work is in the target settings.

Four settings decide whether the extension installs and appears in Settings. Get any one wrong and your app never shows up, with no error message. They are marked must match below.

Step 1: add the package to your app

In Xcode, choose File > Add Package Dependencies and paste:

https://github.com/dimondevceo/callerapi-sdk

Tick both products this time: CallerAPI and CallerAPILiveCallerID. Add both to your app target.

Step 2: create the extension target

Choose File > New > Target. Search for Live Caller ID Lookup Extension. Select it and click Next.

Name it LiveLookup. Confirm Embed in Application points at your app. Click Finish.

Xcode creates the target and a stub Swift file.

Step 3: set the bundle identifier (must match)

Select the LiveLookup target, open Signing & Capabilities, and set the bundle identifier to exactly the one you registered:

com.yourco.app.LiveLookup

[screenshot of the Signing and Capabilities tab showing the nested bundle identifier for the LiveLookup target]

It must start with your app's bundle identifier. iOS finds the extension by that relationship. Any other name means your app never appears in Settings > Apps > Phone > Call Blocking & Identification.

Set the same development team as your app.

Step 4: set the deployment target (must match)

In Build Settings for the LiveLookup target, set iOS Deployment Target to 18.0.

Live Caller ID does not exist before iOS 18. Your app target can stay lower.

Step 5: leave the entitlements file empty

Open LiveLookup.entitlements. It must contain an empty dictionary:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict/>
</plist>

Do not add the Live Caller ID Lookup capability yet. Adding com.apple.developer.identitylookup.live-caller-id-lookup before you have an App Store build breaks signing, and the error you get is amfid ... -413, which does not mention entitlements at all.

Add the capability when you build for TestFlight or the App Store, and only after your relay enrollment is complete.

Step 6: check the extension Info.plist (must match)

Open the LiveLookup Info.plist and confirm these three keys. Xcode usually writes them, and an incomplete file is a common cause of a failed install.

<key>CFBundleExecutable</key>
<string>$(EXECUTABLE_NAME)</string>
<key>CFBundlePackageType</key>
<string>XPC!</string>
<key>EXAppExtensionAttributes</key>
<dict>
    <key>EXExtensionPointIdentifier</key>
    <string>com.apple.live-lookup</string>
</dict>

A missing CFBundleExecutable fails the install with "has missing or invalid CFBundleExecutable in its Info.plist".

Step 7: link the SDK to the extension (must match)

Select the LiveLookup target, open General, and find Frameworks and Libraries. Click the plus button and add CallerAPILiveCallerID.

Adding it to your app target is not enough. The extension is a separate binary and needs its own copy.

Step 8: write the extension

Replace everything in the generated Swift file with this:

The struct name must match your file name. That is the whole extension. The SDK handles the protocol, the network, and the encryption.

Step 9: start the SDK in your app

Add this to application(_:didFinishLaunchingWithOptions:), or to the init of your App struct:

One call does four things. It reports usage for billing and registers the background refresh. It also refreshes the extension when your app opens, and again every time your app returns to the foreground.

That last part matters. Without it, the first call after a long gap has to set up encryption keys while the phone is ringing, and it can miss.

extensionIdentifier must be the same string you set in step 3.

Step 10: add the background task to your app Info.plist

Open your app Info.plist, not the extension one. Add:

<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.callerapi.checkin</string>
    <string>com.yourco.app.lcid.heartbeat</string>
</array>

The second entry must match the heartbeatTaskIdentifier from step 9. Without these, usage reporting stops for users who rarely open your app, and your analytics misbehave or crash.

Step 11: build and confirm the extension shipped

Build to your device. Then confirm the extension is really inside your app:

In the Project Navigator, expand Products.

Right-click your .app and choose Show in Finder.

Right-click the app in Finder and choose Show Package Contents.

Open the Extensions folder.

You must see LiveLookup.appex. If that folder is missing or empty, the extension was not embedded, and nothing later works. Go back to step 2 and check Embed in Application.

iOS step 3: test on a device.

Also adding Call Directory

Skip this if your app only supports iOS 18 and later.

Call Directory is a second extension, for blocking on iOS 15 to 17. It follows the same shape with three differences:

Choose the Call Directory Extension template in step 2.

Use the bundle identifier com.yourco.app.CallDirectory.

Add the App Group group.com.yourco.app to both your app and this extension, in Signing & Capabilities. Call Directory needs it to read the downloaded list.

Copy CallDirectoryExtension/CallDirectoryHandler.swift and AppConfig.swift from the SDK repository into the target. Then edit the two values in AppConfig.swift to match your App Group and bundle identifier.

Then call CallerAPI.CallDirectory.configure and sync from your app. See CALL-DIRECTORY-XCODE.md in the SDK repository for the full walkthrough.

iOS add the extension

iOS step 2: add the extension#

What you are building#

Step 1: add the package to your app#

Step 2: create the extension target#

Step 3: set the bundle identifier (must match)#

Step 4: set the deployment target (must match)#

Step 5: leave the entitlements file empty#

Step 6: check the extension Info.plist (must match)#

Step 7: link the SDK to the extension (must match)#

Step 8: write the extension#

Step 9: start the SDK in your app#

Step 10: add the background task to your app Info.plist#

Step 11: build and confirm the extension shipped#

Next#

Also adding Call Directory#