Usage

This is the technical documentation which describes how to implement the Clever Dialer SDK into your application. For non-technical information about the SDK and its feature set look here: overview

General

Setting Value
minSdkVersion 14
targetSdkVersion 28
compileSdkVersion 28

If the hosting application is built using Gradle, the Clever Dialer SDK can be pulled directly from our Maven repository.

implementation('de.validio.cdand:cdand-sdk:1.5.0:<classifier>@aar') {
    transitive = true
}

The <classifier> has to be replaced with your partnerId, which is provided by us and tells the SDK which hosting application it is being integrated into. To make sure transitive dependencies are being loaded, the flag transitive has to be set to true.

Furthermore, our Maven repository has to be added to your build.gradle.

allprojects {
    repositories {
        maven {
            credentials {
                username "$mavenUser"
                password "$mavenPassword"
            }
            url "https://nexus.validio.de/content/repositories/partner-releases/"
        }
    }
}

TIP

The values for $mavenUser and $mavenPassword are best kept separate from your source and should be set in ~/.gradle/gradle.properties.

Starting with version 1.2.2, our SDK will initialize automatically. Initialization will set a few things up and get the update process for the offline spam number list going.

All web service requests are directed to the Clever Dialer production environment hosted under https://ws.cleverdialer.com/api/1.4 by default. During app development, it can be helpful to point to our dev or staging environment. In order to do this, the URL of the desired environment has to be added to a file named src\<build_type>\res\values\config.xml as shown in the following example.

<string name="cd_sdk_ws_base_url" translatable="false">
    https://ws.dev.cleverdialer.com/api/1.4
</string>

WARNING

In version 1.5.0:
1.) "ws_base_url" has been renamed to "cd_sdk_ws_base_url".
2.) The base path has been changed to "/api/1.4".

The authentication credentials cd_sdk_partner_id and cd_sdk_secret must be stored inside said config.xml file as well. At least, your credentials to our production environment have to be added to src\main\res\values\config.xml. (Saving the dev / staging credentials in their corresponding config.xml files is optional.)

<string name="cd_sdk_partner_id" translatable="false"></string>
<string name="cd_sdk_secret" translatable="false"></string>

WARNING

In version 1.5.0:
1.) "partnerId" has been renamed to "cd_sdk_partner_id".
2.) "secret" has been renamed to "cd_sdk_secret".

ProGuard

If the hosting application project uses ProGuard, it does not have to manually update the ProGuard file, as the Clever Dialer SDK embeds its own ProGuard file. As the SDKs ProGuard rules are specified by using the consumerProguardFiles property inside the defaultConfig block of the SDKs build.gradle file, they will automatically be appended to the ProGuard configuration file of the hosting app. The Clever Dialer SDK defines the following ProGuard rules:

-dontwarn okio.**
-dontwarn okhttp3.**
-keep class okhttp3.** { *; }
-keep interface okhttp3.** { *; }

-dontwarn org.joda.time.**

-keep,includedescriptorclasses class de.validio.cdand.model.** { *; }
-keep,includedescriptorclasses class de.validio.cdand.sdk.model.** { *; }

Permissions

In order to detect phone calls and work correctly, the Clever Dialer SDK requires a set of permissions. The permissions are declared in the AndroidManifest of the SDK and therefore do not need to be entered into the Manifest of the hosting application. As the compileSdkVersion of the SDK is 26 and, starting with Android 6.0 (API level 23), the user is requested to grant permissions at runtime. The user must at least grant the permissions READ_PHONE_STATE and PROCESS_OUTGOING_CALLS at runtime for the caller identification to work. Starting with Android 9 (API level 28) the permission READ_CALL_LOG is required, too. The permission SYSTEM_ALERT_WINDOW has to be granted, to enable the hosting application to draw the Pre-Call Overlay on top of all other apps. All these permissions are requested during the default onboarding process of the SDK.

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<uses-permission android:name="android.permission.PROCESS_OUTGOING_CALLS" />

<uses-permission-sdk-23 android:name="android.permission.READ_CALL_LOG" />

Since the Clever Dialer SDK communicates with the hosting app through events, an additional permission must be added to the AndroidManifest.xml of the hosting application. This enables the hosting app to register for these events. The <classifier> - usually the cd_sdk_partner_id in capitals - must be added as well.

<!-- receive SdkEvents -->
<uses-permission android:name="de.validio.cdand.sdk.SDK_EVENT_PERMISSION_<classifier>"/>

If the Clever Dialer SDK should not show an overlay for phone numbers, which are stored in the users address book, it requires the READ_CONTACTS permission in order to get access to the users address book. The hosting application can decide, if it wants to support this feature. If it does, it has to declare the permission in its AndroidManifest.

<uses-permission android:name="android.permission.READ_CONTACTS" />

Configuration

The Clever Dialer SDK comes with a very flexible, configurable feature set. The core features of the SDK are spam protection, caller ID and alternative suggestions. The hosting app can decide, which features should be supported and available to the user.

In order to configure the SDK, the hosting application must instantiate a Config.Builder and call the support-methods for the desired features. Passing true to these methods means, that a feature should be supported and available to the user. By passing false the feature will be shut off and will not be present in the hosting app. The resulting configuration has to be passed to the static method CleverDialerSdk.configure(Context context, Config config).

A good place to configure the SDK, is the onCreate()-method of the hosting apps Application class:

public class App extends MultiDexApplication {
    @Override
    public void onCreate() {
        super.onCreate();

        Config config = new Config.Builder()
                // TODO: Call support-methods to declare, which
                //  features should be available in the hosting app
                .build();

        CleverDialerSdk.configure(this, config);
    }
}

Options

The class Config.Builder provides support-methods for all configurable features of the SDK. They are listed and discussed in this section.

Spam protection

By default, the SDK will show warnings upon / during (pre-call) and after (post-call) a phone call, if the given phone number is identified as a known spam number. If the hosting app does not want to support this feature, it has to call supportSpamProtection(false).

Caller ID

By default, the SDK will show Pre-Call- and Post-Call Overlays with contact details, whenever a (partner) directory entry was found for a given phone number. If the hosting app does not want to support this feature, it has to call supportCallerId(false).

Alternative suggestions

By default, the SDK will show a Post-Call Overlay with alternative suggestions, if the user tried to call an identified business, but the phone call was not answered and alternatives have been found. If the hosting application does not want to support this feature, it has to call supportAlternativeSuggestions(false).

Notifications

Whenever a Post-Call Overlay is shown, the Clever Dialer SDK will send a notification to the user, too. By clicking the notification, the user can reopen the Post-Call Overlay. If the hosting app does not want to support this feature, it has to call supportNotifications(false).

Address book access

By default, the SDK will enable the user to grant access to his address book. If the user does not want to see any overlays for phone numbers, which are stored in his address book, he has to grant access to his address book. If the hosting app does not want to support this feature, it has to call supportAddressBookAccess(false). Doing so, the user will not be able to deactivate overlays even if the phone number is stored in his address book.

WARNING

If the hosting application wants to support this feature (which it does per default), it has to declare the permission READ_CONTACTS in its AndroidManifest.

Rate-button

By default, the SDK will not collect ratings for directory entries. If the hosting app wants to support this feature, it has to call supportRateButton(true). Doing so, the Post-Call Overlay will contain a button, which allows the user to rate a contact, if the given contact allows it. The hosting app has to react on the click event in order to start its rating-process. See events.

By default, the SDK will show a hint in the Pre-Call Overlay and a clickable booking link in the Post-Call Overlay and alternative suggestions, if the given contact supports online booking. The hosting app has to react on the click event, in order to start the online booking process. See events. If the hosting app should not support online booking, call supportBookingLinks(false).

Profile-button

By default, the Post-Call Overlay will contain a button, which enables the user to open the profile belonging to the given contact. The hosting app has to react on the click event, and must open the corresponding profile page. See events. If the hosting application does not want to provide this feature, it has to call supportProfileButton(false).

Rules

There are three rules, which have to be followed, in order to configure the Clever Dialer SDK correctly. A infringement will cause a ConfigurationException to be thrown.

Spam protection and / or Caller ID

At least spam protection or caller ID (or both) have to be supported by the hosting application.

Alternative suggestions requires Caller ID

If the hosting app wants to provide alternative suggestions, it has to support caller ID, too.

Address book access requires READ_CONTACTS-permission

If the hosting app wants to provide the feature address book access (in order to give the user the chance to decide, that he does not want to see any overlays, for phone numbers, which are stored in his address book) it must declare the permission READ_CONTACTS in the AndroidManifest.

Onboarding

To enable the Clever Dialer SDK, the user has to accept the SDK usage and grant a set of required permissions. The hosting application could either implement its own logic to request all required permissions and ask the user to accept the usage of the SDK, or it could just use the default onboarding process provided by Clever Dialer SDK. Using the default onboarding process, the SDK will care about requesting the permissions and ask the user for approval. The hosting application can decide when and how often a user should be asked to activate the SDK (if he does not do it at first attempt).

To use the default onboarding process, the hosting application just has to call the static method:

CleverDialerSdk.enableOnboardingProcess(Context context, boolean isCdSdkUsageAccepted);

WARNING

It is important, that the hosting application passes the right value for isCdSdkUsageAccepted. Otherwise users, who already accepted the usage of Clever Dialer SDK, would be asked again.

If the hosting application did or does not use the default onboarding process until now, it has to care about a flag / SharedPreference, which indicates that the user accepted the usage of the Clever Dialer SDK. It is important to pass this value as param isCdSdkUsageAccepted when enableOnboardingProcess() is called. Otherwise users, who already accepted the usage of the SDK, would be asked again.

A good place to call enableOnboardingProcess() would be the onStart()-method of the hosting apps MainActivity:

@Override
protected void onStart() {
    super.onStart();
    CleverDialerSdk.enableOnboardingProcess(this, isCdSdkUsageAccepted, new Frequency(7, 3, 90));
}

If the default onboarding process is used, the hosting application has to react to some events, too.

By calling enableOnboardingProcess(), the hosting app tells the SDK, that it is responsible for onboarding from now on. Whenever this method is called, the SDK will check if the usage was accepted and if each mandatory permission was granted. If any approval is missing, the SDK will start to ask the user to agree. If the user denies this by clicking the negative button in the onboarding overlays, the decision will be postponed. When the user will be asked again is defined by the frequency, in order to prevent annoying him. This frequency takes three values into account:

  • intervalDays (default: 7): Amount of days which have to be passed before the user is asked again
  • limit (default: 3): Amount of times the user will be asked to agree, before the requests are paused for revivalDays.
  • revivalDays (default: 90): Amount of days which have to be passed to reactivate the onboarding process.

This means:
If the user chooses NOT NOW in the overlay he will be asked again in 7 days. If he postpones each time, he will only be asked a maximum of 3 times. If he postpones again after that, the onboarding process will be paused for 90 days. After that time has passed, the process will be repeated. The hosting app can specify different values by passing an object of type Frequency.java to enableOnboardingProcess().

If in a later version of the hosting app, the application should be changed to implement its own onboarding process, it has to signal, that the SDK is not responsible for onboarding anymore. This can be done by calling:

CleverDialerSdk.disableOnboardingProcess(Context context);

After calling this static method, the SDK will stop onboarding and will not request the permissions anymore. The hosting application will have to handle the activation / deactivation of all SDK features by it self.

Settings page

The Clever Dialer SDK contains a default settings page, which can optionally be used by the hosting app. The settings page is created dynamically and will provide settings according to the chosen configuration. It enables the user to activate / deactivate the core features of the SDK according to his wishes.

Preferences

Depending on the configuration which the hosting application set, the settings page will or will not contain the following entries:

Spam protection

The user can decide, if he wants to be warned against untrustworthy numbers that are considered spam.

<CheckBoxPreference
    android:key="@string/cd_sdk_pref_spam_protection_enabled"
    android:defaultValue="@bool/cd_sdk_default_enable_spam_protection" />

Default: true

Caller ID

The user can decide, if the SDK should try to identify phone numbers and display contact details during / after the call.

<CheckBoxPreference
    android:key="@string/cd_sdk_pref_caller_id_enabled"
    android:defaultValue="@bool/cd_sdk_default_enable_caller_id" />

Default: true

Alternative suggestions

The user can decide, if the SDK should display alternative businesses after an outgoing call has been finished unsuccessfully.

<CheckBoxPreference
    android:key="@string/cd_sdk_pref_alternative_suggestions_enabled"
    android:defaultValue="@bool/cd_sdk_default_enable_alternative_suggestions" />

Default: true

Address book access

Determines, if the sdk should access the local address book of the user. If so, it does not show additional information for a phone number during / after a call if the number is stored in the local address book.

<CheckBoxPreference
    android:key="@string/cd_sdk_pref_address_book_access_enabled"
    android:defaultValue="@bool/cd_sdk_default_enable_address_book_access" />

Default: false

WARNING

If the user wants to activate this feature (which means, that he does not want to see overlays, if the given phone number is stored in his address book), he has to grant the permission READ_CONTACTS. Therefore the hosting application has to add the permission to its AndroidManifest.

Notifications

The user can decide, if th SDK should send a notification as soon as the call has been ended and further details for the phone number have been found.

<CheckBoxPreference
    android:key="@string/cd_sdk_pref_notifications_enabled"
    android:defaultValue="@bool/cd_sdk_default_enable_notifications" />

Default: true

Default values

As shown above, the Clever Dialer SDK defines the default_enable state for all the listed preferences. However, the hosting application is able to override these values. The default values will define the behavior of the core features, as long as the user does not change the settings himself.

To override the default values, (and therefore the default behavior) of the core features, the following entries can be added to the file src\main\res\values\config.xml which has already been created to add the SDK credentials:

<!-- Declare the default enabled state for the (supported) core features.
Can be changed by the user at runtime within the default settings page. -->
<bool name="cd_sdk_default_enable_spam_protection">true</bool>
<bool name="cd_sdk_default_enable_caller_id">true</bool>
<bool name="cd_sdk_default_enable_alternative_suggestions">true</bool>
<bool name="cd_sdk_default_enable_address_book_access">false</bool>
<bool name="cd_sdk_default_enable_notifications">true</bool>

Usage

The hosting application has two options:
1.) It could either add each of the listed preferences as a TwoStatePreference (for example CheckBoxPreference) to its PreferenceScreen and implement the logic behind (e.g. it should care about requesting the permission READ_CONTACTS, if the user wants to deactivate overlays for contacts, which are stored locally).
2.) It could just use the default settings page, which is included in the Clever Dialer SDK.

To use the default settings page, the Activity CdSdkSettingsActivity.java has to be added to AndroidManifest.xml of the hosting application:

<activity
    android:name="de.validio.cdand.sdk.controller.activity.CdSdkSettingsActivity" />

Now, the hosting application can decide, when to open / show this screen. For example, the hosting app could add a MenuItem to its NavigationView or an entry to its PreferenceScreen and open the SDKs settings page, when the user clicks this item.

To open the settings, the Activity can be started by simply calling the static method:

CleverDialerSdk.openSettingsActivity(Context context, boolean isCdSdkUsageAccepted);

WARNING

It is important, that the hosting application passes the right value for isCdSdkUsageAccepted when the settings page is opened. Otherwise users, who already accepted the usage of Clever Dialer SDK, would be asked again.

The default settings page includes an element, where the user can activate the SDK and will ask him to do so, if he did not do it yet. If the hosting application did or does not use the default onboarding process until now, it has to care about a flag / SharedPreference, which indicates that the user accepted the usage of the Clever Dialer SDK. It is important to pass this value as param isCdSdkUsageAccepted when openSettingsActivity() is called. Otherwise users, who already accepted the usage of Clever Dialer SDK, would be asked again.

The default settings page can be changed and styled easily:

  • If the hosting application wants to change the title in the Toolbar of the settings page, it just has to add android:label="@string/title" to the activity-tag in the AndroidManifest-entry.
  • If the hosting application wants to change the style of the settings page, it could override the file cd_sdk_preferences_screen.xml. For example, instead of CheckBoxPreference another type of TwoStatePreference (e.g. SwitchPreference) could be used.
  • The texts for android:title or android:summary, referenced in cd_sdk_preferences_screen.xml, could be changed, as well.
  • By default the settings page will use the colors of the standard AppTheme. To individualize the page, a different theme can be defined in the src\main\res\values\styles.xml. By setting the colors colorPrimary, colorPrimaryDark and colorAccent the displayed colors can be adjusted. Adding the created theme to the activity-tag in the AndroidManifest.xml will set the preferred style for the screen.

If the hosting application uses the default settings page of the Clever Dialer SDK, it has to react to some events, too.

Status reporting

If the hosting application uses the default onboarding process and the default settings page, it can query the current SDK status at any time. Therefore it just has to call the static method CleverDialerSdk.getStatus(Context context), which will provide an object of type Status, to describe the current state of the SDK.

Description of the class Status:

Value Method & description
boolean
isCdSdkUsageAccepted()

Returns a boolean-flag, which explains, whether the user accepted the usage of the SDK, or not. Will be true, if he did so.
boolean
arePermissionsGranted()

Returns a boolean-flag, which explains, whether the user granted the mandatory permissions, which are required by the SDK to work correctly, or not. As the permission READ_CONTACTS is optional, this permission is not taken into account here. Furthermore, the permission SYSTEM_ALERT_WINDOW is ignored here, too, as the SDK will for example be able to show Post-Call Overlays, even without this permission.
Set<CoreFeatureState>
getCoreFeatureStates()

Returns a Set of CoreFeatureState dependend on the SDK features, which are supported by the hosting application. Features which are not supported, will not be listed here. A CoreFeature is a SDK feature, which can be supported by the hosting application and enabled / disabled by the user via the default settings page at runtime.

Description of the class CoreFeatureState:

Value Method & description
Label
getName()

Returns the name of the feature.
boolean
isActive()

Returns a boolean-flag to describe, whether this feature is acitve or not. A feature will be active, if the user accepted the usage of the SDK, granted all mandatory permissions and did not disable it in the default settings page.

The Status-object will enable the hosting application, to find out if a user accepted the usage of the SDK and if he granted all mandatory permissions. Furthermore it will get insights in the current state of the SDKs CoreFeatures. As mentioned in the table above, a CoreFeature is a SDK feature, which can be supported by the hosting app and be enabled / disabled by the user at runtime via the default settings page. There are five features, which match this requirements: SPAM_PROTECTION, CALLER_ID, ALTERNATIVES, ADDRESS_BOOK_ACCESS, NOTIFICATIONS. The Set of CoreFeatureStates will contain an entry for each of these features, as long as it is supported by the hosting application. If the user accepted the usage of the SDK (isCdSdkUsageAccepted()) and granted all the mandatory permissions (arePermissionsGranted()) but the feature is still inactive, this proves that the user deactivated it via the settings page.

Example usage:

public class MainActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // ...
        Status status = CleverDialerSdk.getStatus(this);

        if (status.isCdSdkUsageAccepted() && status.arePermissionsGranted()) {
            // The user accepted the usage of the SDK and granted all mandatory
            // permissions. Analyze the current state of the features, to find
            // out, if a feature has been disabled by the user.
            for (CoreFeatureState feature : status.getCoreFeatureStates()) {
                Log.d(TAG, feature.getName() + " isActive " + feature.isActive());
            }
        }
    }
}

Events

On many occasions, the Clever Dialer SDK sends events to the hosting app. Such an event, which is represented by the class SdkEvent, is being triggered for example when an overlay is being shown or a user action is being registered. Some of these events are mandatory and must be handled by the hosting app. Others are optional and for reporting purpose only.

Event model

A SdkEvent always contains values of type Category and Action. In most of the cases a value of type Label is available, too. The combination of these three values describes, what caused the event to be fired. Dependent on the trigger of the event, further relevant variables are set, which enable the hosting app to extract all the important information to react accordingly.

Methods of the class SdkEvent:

Value Method & description
Category
getCategory()

Returns the Category.
Action
getAction()

Returns the Action.
Label
getLabel()

Returns the Label if available, otherwise null.
String
getPhoneNumber()

Returns the phone number which caused the overlay impression. May be null for optional reporting events and events which do not require this field.
String
getSelectedPhoneNumber()

Returns the phone number, which the user selected to call in an overlay. As a contact can have more than one number, or the user might select an alternative suggestion, selectedPhoneNumber may differ from the phone number returned by getPhoneNumber(). Returns null for all other events.
List<String>
getRawContacts()

Returns the list of contacts (raw representation according to the partner API), which were shown in the overlay. May be null for optional reporting events or if no raw contact exists (e.g. spam call).
int
getContactIndex()

Returns the list index of the contact, which is relevant in the present context.
String
getRelevantRawContact()

Returns the relevant raw contact (the contact that caused the overlay impression or if a field of a [alternative] contact has been selected, the associated contact). May be null.

For a regular Pre- or Post-Call Overlay (PRECALL_OVERLAY, POSTCALL_OVERLAY), the list of raw contacts will just contain one element and the index will be 0, as these overlays always just display one contact at a time. In case of an overlay, which was shown in order to warn the user against a spam call (PRECALL_SPAM_OVERLAY, POSTCALL_SPAM_OVERLAY), the list of contacts will be null, as no raw contact exists. In case of an overlay, which shows alternative suggestions, (POSTCALL_ALTERNATIVES_OVERLAY) the list of (raw) contacts will contain all the contacts, which have been displayed to the user. The first element is always the original contact, which was found for the given phone number, followed by the alternative suggestions.

WARNING

The raw contact is the raw representation of a contact according to the partner API and its version used by the Clever Dialer Webservice. Therefore it might change if the partner API changes. The hosting app must be prepared and robust to deal with those changes and stay compatible.

Example

When a Post-Call Overlay with three alternative suggestions (maximum) is shown after an outgoing phone call, the SdkEvent reported to the hosting application will contain the following information:

Method Value
getCategory()
POSTCALL_ALTERNATIVES_OVERLAY
getAction()
OUTGOING_CALL
getLabel()
The <partnerId> in capitals.
getPhoneNumber()
The phone number which caused the overlay impression.
getSelectedPhoneNumber()
Null, as no phone number has been selected inside of the overlay.
getRawContacts()
The list of four (raw) contacts which have been displayed to the user. The first element is always the original contact, which was found for the given phone number, followed by the alternative suggestions.
getContactIndex()
As the original contact is always the first in the list and the user did not interact with the list yet, the index will be 0.
getRelevantRawContact()
Will retrive the original contact which was found for the given phone number and shown on top of the overlay.

Now, if the user clicks on the phone number of the second alternative suggestion, in order to call this contact, the SdkEvent reported to the hosting application will look like this:

Method Value
getCategory()
POSTCALL_ALTERNATIVES_OVERLAY
getAction()
CLICK
getLabel()
NUMBER
getPhoneNumber()
The phone number which caused the overlay impression.
getSelectedPhoneNumber()
The phone number of the second alternative suggestion, which the user selected to call now.
getRawContacts()
The list of four (raw) contacts which have been displayed to the user.
getContactIndex()
As the user selected the second alternative suggestion, the index will be 2.
getRelevantRawContact()
Will retrive the raw contact of the second alternative suggestion.

Event handling

To be able to listen to and react on these events, the class AbstractCdSdkBroadcastReceiver must be extended by the hosting application. This class provides abstract methods, which are called, whenever an action takes place, which has to be handled by the hosting app.

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    // TODO Implement abstract methods to react on events …
}

Furthermore, this implementation of AbstractCdSdkBroadcastReceiver must be registered in the AndroidManifest.xml of the hosting application.

<receiver android:name=".receiver.SampleCdSdkBroadcastReceiver"
          android:exported="false">
    <intent-filter>
        <action android:name="de.validio.cdand.sdk.SDK_EVENT"/>
    </intent-filter>
</receiver>

Apart from that, the permission de.validio.cdand.sdk.SDK_EVENT_PERMISSION_<classifier> must be added to AndroidManifest.xml as described under permissions.

<!-- receive SdkEvents (e.g. tracking) -->
<uses-permission android:name="de.validio.cdand.sdk.SDK_EVENT_PERMISSION_<classifier>"/>

Now, the hosting application is ready to receive SdkEvents.

Mandatory events

Most of the mandatory events, which must be handled by the hosting application, are triggered by a click in an overlay. In this case, the Category describes the overlay, which was shown to the user and can therefore have one of the values ACTIVATION_OVERLAY, POSTCALL_OVERLAY, POSTCALL_SPAM_OVERLAY or POSTCALL_ALTERNATIVES_OVERLAY. The Action will have the value CLICK. The Label transfers the information, which field has been clicked. The class AbstractCdSdkBroadcastReceiver provides abstract methods for all these (click) events. By implementing it, the hosting application can decide, how to react. The hosting app can either implement its own logic here or use the static methods provided in the class DefaultEventHandler.

WARNING

The hosting application might want to parse the raw contact (contained in the SdkEvent), in order to extract certain fields to handle some of the following (click) events correctly. If so, the code has to be robust against changes in the partner API, as the raw contact depends on the version of the partner API which is used by the Clever Dialer Webservice and might change over time. As the declared DefaultEventHandler methods do not need the raw contact, they can always be safely used as a fallback:

String rawContact = event.getRelevantRawContact();

try {
    // TODO: Parse the given raw contact to proceed
} catch (Exception e) {
    // Could not parse the given raw contact
    // TODO: Use the declared DefaultEventHandler
}

onUsageAccepted(Context context, SdkEvent event)

If the hosting application uses the default onboarding process or the default SDK settings-page, this method will be called, when the user accepts the usage of the Clever Dialer SDK by clicking the positive button in the activation overlay.

SdkEvent states:

Category Action Label
ACTIVATION_OVERLAY CLICK ACCEPT

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onUsageAccepted(Context context, SdkEvent event) {
        DefaultEventHandler.logEvent(event);
        // TODO Activate all caller ID functionality if it has been deactivated
        //  upfront
    }  
}

TIP

This is the right place, to (re-)activate all caller ID functionality, if it has been deactivated upfront.

onInfoLinkClicked(Context context, SdkEvent event)

If the hosting application uses the default onboarding process or the default SDK settings-page, this method will be called, when the user clicks on an (info)-link, inside of the (activation) overlays of the Clever Dialer SDK. The SdkEvent Label will transfer the information, which topic the user is interested in (according to the current step within the onboarding process). As a reaction, the hosting app should provide detailed information.

SdkEvent states:

Category Action Label
DYNAMIC_INFORMATION_LINK CLICK ACTIVATION
DYNAMIC_INFORMATION_LINK CLICK SYSTEM_ALERT_WINDOW_PERMISSION
DYNAMIC_INFORMATION_LINK CLICK DEVICE_SETTINGS

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
@Override
    protected void onInfoLinkClicked(Context context, SdkEvent event) {
        switch (event.getLabel()) {
            case ACTIVATION:
                // The user is about to activate the SDK.
                // Now he wants to get more information about the features.
                // TODO: Open a page where the SDK-features are described
                break;
            case SYSTEM_ALERT_WINDOW_PERMISSION:
                // The user needs additional information to grant the
                // SYSTEM_ALERT_WINDOW-permission.
                // TODO: E.g. show FAQs
                break;
            case DEVICE_SETTINGS:
                // The user is running a "huawei", "samsung" or "xiaomi"
                // device. On these devices, additional settings are
                // required in order to make the SDK work correctly.
                // TODO: Show instructions for those settings
                break;
            default:
                DefaultEventHandler.logEvent(event);
                break;
        }
    }   
}

TIP

The SDK provides default webpages (powered by Clever Dialer) for all these cases which contain all the relevant information to enable the user to proceed without any hazzle. These webpages can easily be opened by calling DefaultEventHandler.onInfoLinkClicked(context, event).

The hosting application can either implement its own logic or just call the SDKs static method DefaultEventHandler.onInfoLinkClicked(context, event) to handle this event. If the SDKs handler is used, it will open the browser app to show a matching webpage (powered by Clever Dialer) for each of the cases to enable the user to find the relevant information he needs. The webpages are styled in the hosting applications corporate design and will show the partner logo in the top. The links to those webpages are shown in the following table.

Label Description & Link
ACTIVATION
The user is about to activate the SDK and wants to get more information about the features.
https://www.cleverdialer.app/client/demo/features
SYSTEM_ALERT_WINDOW_PERMISSION
The user needs additional information to grant the SYSTEM_ALERT_WINDOW-permission.
https://www.cleverdialer.app/client/demo/precall
DEVICE_SETTINGS
The user is running a "huawei", "samsung" or "xiaomi" device. On these devices, additional settings are required in order to make the SDK work correctly. He needs some instructions.
https://www.cleverdialer.app/client/demo/huawei

TIP

To open these webpages in the corresponding partner design (showing the partner logo on the top), the path segment "demo" has to be replaced with your <partnerId>.

onSettingsClicked(Context context, SdkEvent event)

When the user clicks the settings-button within one of the overlays, the sdk settings screen needs to be opened within the hosting app.

SdkEvent states:

Category Action Label
POSTCALL_OVERLAY CLICK SETTINGS
POSTCALL_SPAM_OVERLAY CLICK SETTINGS
POSTCALL_ALTERNATIVES_OVERLAY CLICK SETTINGS

Example implementation:
If the hosting application uses the default settings page, which is included in the Clever Dialer SDK, this method could be implemented as simple as this:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onSettingsClicked(Context context, SdkEvent event) {
        CleverDialerSdk.openSettingsActivity(context, isCdSdkUsageAccepted);
    }    
}

onBookingClicked(Context context, SdkEvent event)

If the hosting app supports online booking this method is called, when the user clicks on the booking link within an overlay. As a reaction to this event, the hosting application could for example open the browser app and start the corresponding online booking process.

SdkEvent states:

Category Action Label
POSTCALL_OVERLAY CLICK BOOKING_LINK
POSTCALL_ALTERNATIVES_OVERLAY CLICK BOOKING_LINK

As The POSTCALL_SPAM_OVERLAY does not contain a booking link, the Category can only be POSTCALL_OVERLAY or POSTCALL_ALTERNATIVES_OVERLAY.
If the Category is POSTCALL_OVERLAY, a call to event.getRelevantRawContact() will retrieve the raw representation of the contact, which was shown in the overlay.
If the Category is POSTCALL_ALTERNATIVES_OVERLAY, this could mean, that the user clicked on the booking link of the original contact entry in the top of the overlay, or the user has chosen one of the alternative suggestions. A call to event.getContactIndex() will clarify and event.getRelevantRawContact() will again retrive the corresponding raw contact.

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onBookingClicked(Context context, SdkEvent event) {
        // A contact's booking link has been clicked. Get the associated contact,
        // which is transferred in `SdkEvent`, parse it and extract the relevant
        // data to proceed.

        // As both, the `POSTCALL_OVERLAY` and `POSTCALL_ALTERNATIVES_OVERLAY`
        // contain booking links, this method might have been called, because
        // the user clicked the booking link of an alternative suggestion.
        // If it is relevant for the hosting application, to know, in which type
        // of overlay this click occurred (for example for tracking purpose),
        // event.getCategory() will retrieve this information.

        // If the category is of type `POSTCALL_ALTERNATIVES_OVERLAY`,
        // `event.getContactIndex()` will point out, which contact has been
        // selected to start the online booking process.

        String rawContact = event.getRelevantRawContact();

        // TODO Parse the given rawContact, extract relevant data and start
        //  the booking process
    }
}

TIP

Instead of implementing its own logic, the hosting application could just call the static method DefaultEventHandler.onBookingClicked(context, event), which will open the booking link in the browser app.

onRateClicked(Context context, SdkEvent event)

If the hosting app enabled the rate-feature for contacts, this method will be called, when the user clicks the rate-button within an overlay. As a reaction to this event, the hosting application should start its rating process for the given contact.

SdkEvent states:

Category Action Label
POSTCALL_OVERLAY CLICK RATE
POSTCALL_ALTERNATIVES_OVERLAY CLICK RATE

As the POSTCALL_SPAM_OVERLAY does not contain a rate-button, the Category can only be POSTCALL_OVERLAY or POSTCALL_ALTERNATIVES_OVERLAY.
If the Category is POSTCALL_OVERLAY, a call to event.getRelevantRawContact() will retrieve the raw representation of the contact, which was shown in the overlay.
If the Category is POSTCALL_ALTERNATIVES_OVERLAY, this could mean, that the user clicked on the rate-button of the original contact entry in the top of the overlay, or the user has chosen one of the alternative suggestions. A call to event.getContactIndex() will clarify and event.getRelevantRawContact() will again retrive the corresponding raw contact.

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onRateClicked(Context context, SdkEvent event) {
        String rawContact = event.getRelevantRawContact();
        // TODO Parse the given rawContact, extract relevant data and start the
        //  rating process
    }
}

onAddressClicked(Context context, SdkEvent event)

This method will be called, when the user clicks an address within an overlay. As a reaction to this event, the hosting application should e.g. show a map for the corresponding location.

SdkEvent states:

Category Action Label
POSTCALL_OVERLAY CLICK ADDRESS
POSTCALL_ALTERNATIVES_OVERLAY CLICK ADDRESS

As the POSTCALL_SPAM_OVERLAY does not contain an address, the Category can only be POSTCALL_OVERLAY or POSTCALL_ALTERNATIVES_OVERLAY.
If the Category is POSTCALL_OVERLAY, a call to event.getRelevantRawContact() will retrieve the raw representation of the contact, which was shown in the overlay.
If the Category is POSTCALL_ALTERNATIVES_OVERLAY, this means, that the user clicked on the address of an alternative suggestions, as the address of the original contact in the top of the overlay is not clickable. A call to event.getContactIndex() will clarify which alternative has been chosen and event.getRelevantRawContact() will again retrive the corresponding raw contact.

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onAddressClicked(Context context, SdkEvent event) {
        String rawContact = event.getRelevantRawContact();
        // TODO Parse the given rawContact, extract the address and e.g. show a
        //  map for the location
    }
}

TIP

Instead of implementing its own logic, the hosting application could just call the static method DefaultEventHandler.onAddressClicked(context, event), which will open maps for the given address.

onWebsiteClicked(Context context, SdkEvent event)

This method will be called, when the user clicks the contacts website link within an overlay. As a reaction to this event, the hosting application should e.g. open the browser app for the given link.

SdkEvent states:

Category Action Label
POSTCALL_OVERLAY CLICK WEBSITE
POSTCALL_ALTERNATIVES_OVERLAY CLICK WEBSITE

As the POSTCALL_SPAM_OVERLAY does not contain a weblink, the Category can only be POSTCALL_OVERLAY or POSTCALL_ALTERNATIVES_OVERLAY.
If the Category is POSTCALL_OVERLAY, a call to event.getRelevantRawContact() will retrieve the raw representation of the contact, which was shown in the overlay.
If the Category is POSTCALL_ALTERNATIVES_OVERLAY, this means, that the user clicked on the website link of an alternative suggestions, as the original contact in the top of the overlay contains none. A call to event.getContactIndex() will clarify which alternative has been chosen and event.getRelevantRawContact() will again retrive the corresponding raw contact.

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onWebsiteClicked(Context context, SdkEvent event) {
        String rawContact = event.getRelevantRawContact();
        // TODO Parse the given rawContact, extract the weblink and e.g. open
        //  browser app
    }
}

TIP

Instead of implementing its own logic, the hosting application could just call the static method DefaultEventHandler.onWebsiteClicked(context, event), which will open the browser app for the given link.

onPhoneNumberClicked(Context context, SdkEvent event)

This method will be called, when the user clicks on a phone number within an overlay. As a reaction to this event, the hosting application should for example start a phone call.

SdkEvent states:

Category Action Label
POSTCALL_OVERLAY CLICK NUMBER
POSTCALL_SPAM_OVERLAY CLICK NUMBER
POSTCALL_ALTERNATIVES_OVERLAY CLICK NUMBER

As each type of overlay is triggered by a phone call, there is always an underlying phone number. Therefore the Category can be POSTCALL_OVERLAY, POSTCALL_SPAM_OVERLAY or POSTCALL_ALTERNATIVES_OVERLAY. However, the phone number, which triggered the overlay might differ from the phone number, which the user selected to call now (for example, when the user selected the phone number of an alternative suggestion).
To get access to the phone number, which the user wants to call, the hosting application can safely call event.getSelectedPhoneNumber().
If the hosting application wants to know, which contact this phone number belongs to, it has to take the Category into account: If the Category is POSTCALL_SPAM_OVERLAY, there is no contact. Therefore the method event.getRelevantRawContact() will return null.
If the Category is POSTCALL_OVERLAY, the method event.getRelevantRawContact() will return the corresponding contact, as this type of overlay only contains one contact.
If the Category is POSTCALL_ALTERNATIVES_OVERLAY, a call to event.getContactIndex() will clarify which contact the selected phone number belongs to and event.getRelevantRawContact() will again retrive the corresponding raw contact.

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onPhoneNumberClicked(Context context, SdkEvent event) {
        String phoneNumber = event.getSelectedPhoneNumber();
        // TODO Start a phone call or open the default dialer app for the given
        //  phone number
    }
}

TIP

Instead of implementing its own logic, the hosting application could just call the static method DefaultEventHandler.onPhoneNumberClicked(context, event), which will open the default dialer app for the given phone number.

onProfileClicked(Context context, SdkEvent event)

This method will be called, when the user clicks the profile-button in the Post-Call Overlay. As a reaction to this event, the hosting application should open the profile page of the current contact entry.

SdkEvent states:

Category Action Label
POSTCALL_OVERLAY CLICK PROFILE

As the POSTCALL_SPAM_OVERLAY and POSTCALL_ALTERNATIVES_OVERLAY do not contain a profile-button, the Category can only be POSTCALL_OVERLAY. A call to event.getRelevantRawContact() will retrieve the raw representation of the contact, which was shown in the overlay.

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onProfileClicked(Context context, SdkEvent event) {
        String rawContact = event.getRelevantRawContact();
        // TODO Open the profile page of the given contact
    }
}

onSaveClicked(Context context, SdkEvent event)

This method will be called, when the user clicks the save-button in one of the overlays. As a reaction to this event, the hosting application should store the given contact to the address book or at least open the contacts app.

SdkEvent states:

Category Action Label
POSTCALL_OVERLAY CLICK SAVE
POSTCALL_SPAM_OVERLAY CLICK SAVE

As the POSTCALL_ALTERNATIVES_OVERLAY does not contain a save-button, the Category can only be POSTCALL_OVERLAY or POSTCALL_SPAM_OVERLAY.
If the Category is POSTCALL_SPAM_OVERLAY, there is no contact. Therefore the method event.getRelevantRawContact() will return null. Use event.getPhoneNumber() in this case, to get access to at least the phone number, which triggered this overlay.
If the Category is POSTCALL_OVERLAY, the method event.getRelevantRawContact() will return the corresponding contact.

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onSaveClicked(Context context, SdkEvent event) {
        String rawContact = event.getRelevantRawContact();
        
        if (StringUtils.isNotBlank(rawContact)) {
            // TODO Save the available contact details to the users address book
        } else {
            String phoneNumber = event.getPhoneNumber();
            // TODO As no rawContact is available, save at least the phone number
        }
    }
}

TIP

Instead of implementing its own logic, the hosting application could just call the static method DefaultEventHandler.onSaveClicked(context, event), which will open the default contacts app to insert or edit a contact. Depending on the available contact information, the corresponding fields will be pre-filled.

onTroubleshootingClicked(Context context, SdkEvent event)

If the hosting application uses the default settings page, the user will be able to request help by clicking on the "troubleshooting" element within the settings. The hosting app should handle this click by showing some instructions or give the user the chance to send an email to the support.

SdkEvent states:

Category Action Label
SETTINGS CLICK TROUBLESHOOTING

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onTroubleshootingClicked(Context context, SdkEvent event) {
        // TODO: The user needs help. Let him send an email to the support or
        // show some instructions or FAQs in order to solve his problems.
    }
}

TIP

Instead of implementing its own logic, the hosting application could just call the static method DefaultEventHandler.onTroubleshootingClicked(context), which will open the link https://www.cleverdialer.app/client/demo/troubleshooting. The corresponding webpage is powered by Clever Dialer and will show the partner logo on the top.

Optional events

Besides the mandatory events, there are optional events, which are mainly used for reporting purpose only. The hosting application can ignore these events totally. However, if the hosting app is interested in these events, too, it can override onOptionalEvent(Context context, SdkEvent event) in its implementation of AbstractCdSdkBroadcastReceiver. To get insights in the event, the hosting application can evaluate Category, Action and Label. Depending on the event, additional values will be set, as described in the section event model.

Example implementation:

public class SampleCdSdkBroadcastReceiver extends AbstractCdSdkBroadcastReceiver {
    @Override
    protected void onOptionalEvent(Context context, SdkEvent event) {
        // TODO Evaluate event.getCategory(), event.getAction() and event.getLabel()
        //  to get insights in the given event
    }
}

In the following section, the possible optional events are listed.

Overlay impressions

Whenever an overlay is shown, the Clever Dialer SDK sends an event, to inform the hosting app. The Category describes the overlay, which was shown. When it was shown on start of the phone call, the Category can be of type PRECALL_OVERLAY or PRECALL_SPAM_OVERLAY. After the phone call, the overlay is of type POSTCALL_OVERLAY, POSTCALL_SPAM_OVERLAY or POSTCALL_ALTERNATIVES_OVERLAY. The Action will transfer information about the call type. At start of the phone call, it can be of type INCOMING_CALL or OUTGOING_CALL. When the phone call is finished, it can be of type MISSED_CALL, too. A MISSED_CALL is an INCOMING_CALL, which was not answered by the user. The Label can be <partnerId> in capital letters or SPAM, depending on the data, which was shown in the overlay.

Category Action Label
PRECALL_OVERLAY INCOMING_CALL
OUTGOING_CALL
<partnerId>
PRECALL_SPAM_OVERLAY INCOMING_CALL
OUTGOING_CALL
SPAM
POSTCALL_OVERLAY INCOMING_CALL
OUTGOING_CALL
MISSED_CALL
<partnerId>
POSTCALL_SPAM_OVERLAY INCOMING_CALL
OUTGOING_CALL
MISSED_CALL
SPAM
POSTCALL_ALTERNATIVES_OVERLAY INCOMING_CALL
OUTGOING_CALL
MISSED_CALL
<partnerId>

First overlay impression

Whenever the Clever Dialer SDK shows an overlay of type POSTCALL_OVERLAY, POSTCALL_SPAM_OVERLAY or POSTCALL_ALTERNATIVES_OVERLAY for the first time, it will additionally show a hint to the user, to describe the overlay and its purpose. The hosting app will be notified about this hint impression.

Category Action Label
POSTCALL_OVERLAY
POSTCALL_SPAM_OVERLAY
POSTCALL_ALTERNATIVES_OVERLAY
SHOW_HINT null

Notification events

Whenever the Clever Dialer SDK finds details for a phone number, it will send a notification to the user, when the phone call is ended and an overlay is shown. The user can deactivate these notifications in the default settings page. When a notification is clicked, the associated overlay will be opened.

Category Action Label
NOTIFICATION SENT <partnerId>
SPAM
ALTERNATIVES
NOTIFICATION OPENED <partnerId>
SPAM
ALTERNATIVES

Handled click events

There are some click events, which are handled by the Clever Dialer SDK automatically. However, the hosting application will be notified as well.

Category Action Label
ACTIVATION_OVERLAY CLICK POSTPONE

This event will be fired, when the user postponed the onboarding process by clicking the negative button in the corresponding ACTIVATION_OVERLAY. The user will be re-asked again in the defined frequency.

Category Action Label
POSTCALL_OVERLAY CLICK ALTERNATIVES

By clicking the SHOW_ALTERNATIVE-button in a POSTCALL_OVERLAY, the user is able to open the POSTCALL_ALTERNATIVES_OVERLAY.

Category Action Label
POSTCALL_SPAM_OVERLAY CLICK PROFILE

When the user clicks the more details-button in the POSTCALL_SPAM_OVERLAY, the cleverdialer website will be opened to show more details about the given spam phone number.

Expected obstacles

In some circumstances, the Clever Dialer SDK is not able to show any overlays. Basically, if the caller suppressed his phone number, the users phone was not connected to the internet and no cached data was available or the SDK did not find any data about the phone number, the hosting app will be notified about it. If the user decided, that he does not want to see an overlay, when a phone number is stored in his address book, the SDK sends an event with the Label LOCAL_KNOWN, when a phone call to or from such a contact takes place.

Category Action Label
PRECALL_OVERLAY INCOMING_CALL SUPPRESSED_NUM
PRECALL_OVERLAY INCOMING_CALL
OUTGOING_CALL
NO_CONNECTION
PRECALL_OVERLAY INCOMING_CALL
OUTGOING_CALL
NO_DETAILS
PRECALL_OVERLAY INCOMING_CALL
OUTGOING_CALL
LOCAL_KNOWN
POSTCALL_OVERLAY INCOMING_CALL
OUTGOING_CALL
MISSED_CALL
NO_CONNECTION
POSTCALL_OVERLAY INCOMING_CALL
OUTGOING_CALL
MISSED_CALL
NO_DETAILS
POSTCALL_OVERLAY INCOMING_CALL
OUTGOING_CALL
MISSED_CALL
LOCAL_KNOWN

Settings page events

If the hosting application uses the default settings page of the Clever Dialer SDK, it will be notified whenever the user clicks an element inside the settings page.

Category Action Label
SETTINGS ACTIVATED
DEACTIVATED
UPDATE
SPAM_PROTECTION
SETTINGS ACTIVATED
DEACTIVATED
CALLER_ID
SETTINGS ACTIVATED
DEACTIVATED
ALTERNATIVES
SETTINGS ACTIVATED
DEACTIVATED
ADDRESS_BOOK_ACCESS
SETTINGS ACTIVATED
DEACTIVATED
NOTIFICATIONS

Testing

The integration of the Clever Dialer SDK can be tested by using the class CdSdkTestingActivity.java. This Activity provides a UI, which enables the tester to easily open Pre- and Post-Call Overlays. A set of mocked contacts is included, too.

To use this test interface, the Activity CdSdkTestingActivity.java has to be added to the AndroidManifest.xml of the hosting application:

<activity android:name="de.validio.cdand.sdk.controller.activity.CdSdkTestingActivity" />

Now, the hosting application can decide, when to open / show this screen. The Activity can be started by simply calling the static method:

CleverDialerSdk.openTestingActivity(Context context);

TIP

For example, the hosting application could add this screen only in a debug version of the app. Or it could open up this screen, when some secret user-input was detected (e.g. the settings page has been opened 7 times within 10 sec).

Last Updated: 6/30/2020, 10:09:03 AM