Skip to main content

How to: Enable Caller Id

This page will guide you through enabling Hiya's Call Directory Extension.

Prerequisites​

If you have not done so, please complete the steps in the iOS ClientSDK: Build Integration Guide first.

Project Configuration: Add Info.plist Entries​

SDK initialization requires a few keys to be defined in the Main App’s Info.plist file:

KeyDescriptionRequired
HiyaSharedContainerAppGroupIdThe app group container ID shared between the app and the call directory extensions (e.g. group.com.domain.app)Required
HiyaSpamCallDirectoryBundleIdThe bundle ID of the spam call directory extension target. (e.g. com.domain.app.spamCD)Required
HiyaIdentityCallDirectoryBundleIdThe bundle ID of the identity call directory extension target. (e.g. com.domain.app.identityCD)Optional
HiyaPremiumCallDirectoryBundleIdThe bundle ID of the premium call directory extension target. (e.g. com.domain.app.premiumCD)Optional

In addition to the above keys in the Main App’s Info.plist, each Call Directory Extension must provide the ID of the shared app group container in its Info.plist file under the key HiyaSharedContainerAppGroupId (e.g. group.com.domain.app).

Creating CallKit Directory Extensions​

If necessary, create at least one CallKit Directory Extension. These are added as Targets in your Main App project.

Hiya provides the HiyaCallDirectoryHandler class, which implements all the necessary functionality to begin identifying calls with CallKit. This class does not expose any APIs and it is fully maintained by the SDK. All communication with the embedded call directory extension(s) is handled by the SDK based on the config parameter provided in the Info.plist file as described in the initialization section.

After creating a Call Directory Extension target in your main app, remove the Xcode-generated template code and simply inherit from HiyaCallDirectoryHandler instead of CXCallDirectoryProvider.

Objective-C:

@import HiyaClientSDK;
@interface CallDirectoryHandler : HiyaCallDirectoryHandler
@end

Swift:

import HiyaClientSDK
class CallDirectoryHandler: HiyaCallDirectoryHandler { }

Usage​

Your main application interacts with the Client SDK using the Hiya class. This class is the main public interface of the Hiya iOS SDK and it provides all the necessary APIs for interacting with the Hiya backend APIs as well as managing the call directory extensions for spam detection and call blocking.

Initialization​

The SDK should be initialized at application startup and must be initialized prior to use. We recommend doing this in the AppDelegate’s didFinishLaunchingWithOptions method. See Hiya.initializeSDKWithAPIKey for more information.

SDK Analytics​

The ClientSDK allows the host application to enable or disable the collection of internal SDK analytics with the collectSDKAnalytics parameter to the SDK initializers. When enabled, the SDK may send periodic usage information and crash reports to Hiya's servers for analysis.

Objective-C:

@import HiyaClientSDK;
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Hiya initializeSDKWithAPIKey:[YOUR_API_KEY] collectSDKAnalytics: YES];
    ...
    return YES;
}

Swift:

import HiyaClientSDK
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Hiya.initializeSDK(APIKey:[YOUR_API_KEY], collectSDKAnalytics: true)
    ...
    return true
}

The SDK should be initialized at application startup and must be initialized prior to use. We recommend doing this in the AppDelegate's didFinishLaunchingWithOptions method:

import HiyaClientSDK
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Hiya.initializeSDK(APIKey:[YOUR_API_KEY], collectSDKAnalytics: true)
    ...
    return true
}

Accepting the Terms of Service​

The host application is responsible for obtaining the User's acceptance of the Terms of Service and recording their acceptance by setting the SDK's termsOfServiceAccepted property true. This property should be set after the SDK has been initialized. Once the Terms of Service have been accepted, it is not necessary again on subsequent application launches.

Note: The SDK will not function or perform any network requests until the Terms of Service have been accepted.

App Lifecycle​

In addition to initialization, the SDK provides APIs for various app lifecycle events. These APIs should be implemented in the corresponding AppDelegate or SceneDelegate methods for the SDK to function properly.

  • applicationDidEnterBackground
  • applicationWillEnterForeground
  • applicationDidBecomeActive

Background Updates​

In order to provide up to date spam protection, the SDK can automatically update the spam database and associated CallKit call directories while the host app is backgrounded. The SDK currently supports two background update methods:

  1. Background processing via BGTaskScheduler and BGProcessingTask (Preferred). This “new” background support (available as of iOS 13) gives the SDK much more time than previously available to execute processing tasks in the background, especially if the device is connected to a power source. Currently, the SDK is set to attempt a background processing task every 4 hours, but there is no guarantee the system will call our BGProcessingTask on a set schedule as the system determines the optimal time to run your task based on the current system state (e.g battery level, background usage, cpu load, etc.). For more about adding support for background processing see, Hiya.scheduleProcessingTaskWithIdentifier: and also refer the the example implementation provided in the included HiyaClientSDKDemoApp project.

  2. For users that require < iOS 13 support, the SDK still offers updating via the legacy background update process (Background Fetch, introduced in iOS 7), which allows the developer to request additional processing time when the app goes into the background via: UIApplication.beginBackgroundTask(expirationHandler:) In this case, the system usually gives you an additional 30 seconds or so to finish your background processing task. Our SDK checks how large the incremental update will be before attempting to execute the task. Accordingly, if the number of updates is too large, it won’t attempt to update in the background. To enable support for legacy background updating:

    1. Register for background fetch in the target's capabilities tab
    2. Call the SDKs performFetchWithCompletionHandler method from the app delegate's performFetchWithCompletionHandler

Objective-C:

- (void)application:(UIApplication *)application performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
    [Hiya performFetchWithCompletionHandler:completionHandler];
}

Swift:

func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {

    Hiya.performFetch(completionHandler: completionHandler)
}

Note​

In order for the automatic updates to work properly in the background, the app delegate needs to also implement the handleEventsForBackgroundURLSession method of UIApplicationDelegate and call this SDK method from it.

Objective-C:

- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)(void))completionHandler
{
    [Hiya handleEventsForBackgroundURLSessionWithIdentifier:identifier completionHandler:completionHandler];
}

Swift:

func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {

    Hiya.handleEventsForBackgroundURLSession(identifier: identifier, completionHandler: completionHandler)
}

Logging​

The ClientSDK makes certain log messages available to the host application via a subscription mechanism. Applications that wish to receive log messages from the Client SDK should implement the HiyaClientSDKLogDestination protocol on an object, then subscribe this object to receive log messages. The SDK will forward log messages to this object using the logMessage(_ level: HiyaClientSDKLogLevel, component: String, message: String) method.

HiyaClientSDKLogDestinations can be subscribed or unsubscribed from SDK log messages using the Hiya.addLoggingDestination(_ destination: HiyaClientSDKLogDestination) -> HiyaClientSDKLogDestinationID and Hiya.removeLoggingDestination(_ destinationID: HiyaClientSDKLogDestinationID) methods.

For an example, please see the ExampleLogger class in the accompanying HiyaClientSDKDemo project. This class is an example HiyaClientSDKLogDestination implementation that forwards log messages to the system log. The ExampleLogger class is added as a logging destination in the ViewModel initializer.