Android Guide

To integrate the Spam Control SDK into your Android project, follow these steps:

Adding the Repository

First, add the repository to your project’s build.gradle file:

repositories {
    maven {
        url 'https://packagecloud.io/Wave/Wave/maven2'
    }
}

Add the sdk as a dependency in your module’s build.gradle To always get the latest version:

implementation "br.com.wave:spam-control:+"

To get the latest Minor and Patch versions:

implementation "br.com.wave:spam-control:0.+"

Current latest version: 0.18.0

Initialization

After sync, you should be able to use the SpamControl class. It contains the following methods. Context is expected as parameter in each one. They are:

enableSpamControl: Turns on the service. It checks for the necessary permissions and returns a EnableReturn object that represents the synchronous result. If any permission is missing, an ui will be shown asking for it. You can listen to the result in your onActivityResult and checking the SpamControl.SpamControl_RESULT requestCode. The result code will be android.app.Activity.RESULT_OK or android.app.Activity.RESULT_CANCELED. If it is RESULT_OK, the user granted the permissions and the service is turned on. If it is RESULT_CANCELED, the user denied at least one permission and enableSpamControl should be called again. If all permissions were already granted before calling this method, the ui will not be triggered and the service will start. We expect as parameters an activity, your apiKey (which we provide) and the user’s current phoneNumber. This method requires that the user has internet connection to work. The Environment parameter defines if the service will point to Staging (STG) or Production (PROD) backend. To change Environment, the enable methods need to be called again with the new Environment (after a call to disable). It is important to notice that STG and PROD apiKeys are different. The default value for this parameter is ´PROD´. The subscriptionMode parameter defines how call blocking relates to the client’s subscription, see Subscription. The default value for this parameter is FREE.

val result = SpamControl.enableSpamControl(
    activity = this,
    apiKey = "...",
    phoneNumber = "...", // 5511912345678 (ddi + ddd + phone)
    environment = SpamControl.Environment.PROD,
    subscriptionMode = SpamControl.SubscriptionMode.FREE
)
when (result) {
    SpamControl.EnableReturn.Error.Connection -> { /* No connection when enabling the service */ }
    SpamControl.EnableReturn.Error.EmptyApiKey -> { /* Received apiKey is empty */ }
    SpamControl.EnableReturn.Error.EmptyPhoneNumber -> { /* Received apiKey is empty */ }
    SpamControl.EnableReturn.Success -> { /* Service is active */ }
    SpamControl.EnableReturn.AlreadyOn -> { /* Service is already on, so no action is taken */ }
    SpamControl.EnableReturn.WaitingPermissions -> { /* Waiting for user to grant permissions, listen to onActivityResult */}
}

enableSpamControlSilently: Turns on the service silently. It checks for the necessary permissions and returns a EnableSilentlyReturn object. If any mandatory permission is missing, the service will not be enabled. You can check by calling hasSpamControlPermissions. If all mandatory permissions were already granted before calling this method, the service will start. We expect as parameters a context, your apiKey (which we provide) and the user’s current phoneNumber. The Environment parameter defines if the service will point to Staging (STG) or Production (PROD) backend. To change Environment, the enable methods need to be called again with the new Environment (after a call to disable). It is important to notice that STG and PROD apiKeys are different. The default value for this parameter is ´PROD´. The subscriptionMode parameter works as in enableSpamControl, see Subscription.

val result = SpamControl.enableSpamControlSilently(
    context = this,
    apiKey = "...",
    phoneNumber = "...", // 5511912345678 (ddi + ddd + phone)
    environment = SpamControl.Environment.PROD,
    subscriptionMode = SpamControl.SubscriptionMode.FREE
)
when (result) {
    SpamControl.EnableSilentlyReturn.Error.MissingPermission -> { /* The app is still missing permissions. Please use SpamControl.enableSpamControl instead. */ }
    SpamControl.EnableSilentlyReturn.Error.EmptyApiKey -> { /* Received apiKey is empty */ }
    SpamControl.EnableSilentlyReturn.Error.EmptyPhoneNumber -> { /* Received apiKey is empty */ }
    SpamControl.EnableSilentlyReturn.AlreadyOn -> { /* Service is already on, so no action is taken */ }
    SpamControl.EnableSilentlyReturn.Success -> { /* Service is active */ }
}

disableSpamControl: Turns off the service. This method doesn’t revoke any granted permissions.

SpamControl.disableSpamControl(context = this)

isSpamControlOn: Returns true if the service is on and false if it is off.

SpamControl.isSpamControlOn(context = this)

getCurrentEnvironment: Returns the current environment, which is an enum. Possible values are STG and PROD.

val environment = SpamControl.getCurrentEnvironment(context = this)

hasSpamControlPermissions: Returns true if the app has mandatory Spam Id permission for the service to work. Returns false if it doesn’t.

SpamControl.hasSpamControlPermissions(context = this)

hasSpamControlOptionalPermissions: Returns true if the app has all of the optional permissions (READ_CONTACTS && READ_CALL_LOG). Returns false if at least one permission is missing.

SpamControl.hasSpamControlOptionalPermissions(context = this)

getCalls: Returns a list of PhoneCall objects, each representing a phone call that was registered by our service. Please note that we erase objects that are considered old from time to time.

SpamControl.getCalls(context = this)

data class PhoneCall(
    val id: Int, // Id from calls database
    val phoneNumber: String, // Call's number
    val date: String, // When the call was received
    val name: String?, // Contact's name, if it exists
    val categoryId: Int?, // Category's id, if number is categorized. Same id from Category object. See getCategories method
    val category: String?, // Category's name, if number is categorized. Same name from Category object. See getCategories method
    val isUploaded: Boolean, // If call data was uploaded to backend successfully for metrics
    val status: PhoneCallStatus, // Register what happened to the call during screening. Possible values are described below
    val direction: PhoneCallDirection, // If call was received (IN) or made (OUT)
    val databaseId: String?, // Service database's id that identified the number
)

enum class PhoneCallStatus {
    CATEGORY_FILTERED, // Blocked. Number's category is enabled.
    USER_ALLOWED_CATEGORY, // Not blocked. Number's category is disabled.
    CATEGORY_FILTERED_PREFIX, // Blocked. Number has a prefix related to a category that is enabled.
    CATEGORY_NOT_MAPPED, // Blocked. Number is identified by SpamControl, but doesn't have a category.
    MANUAL_BLOCK, // Blocked. Number was manually blocked by the user.
    NOT_IN_DATABASE, // Not blocked. Number is not identified by SpamControl.
    RELIABLE_NUMBER, // Not blocked. Number was manually unblocked by the user.
    ALLOWED_CONTACT, // Not blocked. Number is a user's contact.
    BLOCKED_PRIVATE_NUMBER, // Blocked. Number is private, not accessible.
    ALLOWED_PENDING_PAYMENT, // Not blocked. User is missing payment.
    UNDEFINED, // Status was not mapped

    NORMAL, // Deprecated. This value is not used for new calls and will be removed soon. Use NOT_IN_DATABASE instead
    SPAM, // Deprecated. This value is not used for new calls and will be removed soon. Use USER_ALLOWED_CATEGORY instead
    RELIABLE, // Deprecated. This value is not used for new calls and will be removed soon. Use RELIABLE_NUMBER instead
    BLOCKED; // Deprecated. This value is not used for new calls and will be removed soon. Use CATEGORY_FILTERED instead

    // Returns true if the call was blocked by SpamControl based on status (call.status.isBlocked()).
    fun isBlocked(): Boolean
}

deleteCalls: Deletes all registered calls from our registry. Returns a DeleteCallsReturn object.

val result = SpamControl.deleteCalls(context = this)
when (result) {
    SpamControl.DeleteCallsReturn.Error.Unknown -> { /* Something wrong happened */ }
    SpamControl.DeleteCallsReturn.Error.NoCallsToDelete -> { /* There are no calls to be deleted */ }
    SpamControl.DeleteCallsReturn.Success -> { /* Deleted successfully */ }
}

getUserSpamNumbers: Returns a list of UserSpamPhoneNumber objects, each representing a specific number that the user manually blocked or allowed receiving calls from.

SpamControl.getUserSpamNumbers(context = this)

data class UserSpamPhoneNumber(
    val phoneNumber: String, // Blocked/Unblocked number.
    val name: String?, // Number's contact name.
    val categoryId: Int?, // Number's category.
    val isBlocked: Boolean, // True if blocked and false if unblocked
    val date: Date? // The date when blocked or unblocked
)

blockNumber: Blocks a number. Pass the number as a trimmed number only string. Returns a BlockReturn object.

val result = SpamControl.blockNumber(context = this, number = "...")
when (result) {
    SpamControl.BlockReturn.Error.Unknown -> { /* Something wrong happened */ }
    SpamControl.BlockReturn.Error.NumberLengthSmall -> { /* The provided number is not accepted for being too small. The is a `minLength` field inside this data class representing the current minimum length. It is set as 3 */ }
    SpamControl.BlockReturn.Error.NumberLengthLong -> { /* The provided number is not accepted for being too long. The is a `maxLength` field inside this data class representing the current maximum length. It is set as 14 */ }
    SpamControl.BlockReturn.AlreadyBlocked -> { /* The provided number is already blocked */ }
    SpamControl.BlockReturn.Success -> { /* Number blocked successfully */ }
}

unblockNumber: Unblocks a number. Pass the number as a trimmed number only string. Returns a UnblockReturn object.

val result = SpamControl.unblockNumber(context = this, number = "...")
when (result) {
    SpamControl.UnblockReturn.Error.Unknown -> { /* Something wrong happened */ }
    SpamControl.UnblockReturn.Error.NumberIsNotBlocked -> { /* The provided number is not currently blocked */ }
    SpamControl.UnblockReturn.Success -> { /* Number unblocked successfully */ }
}

getCategories: Returns a list of Category objects, each representing a category of phone numbers that can be all blocked/unblocked at once. Only categories marked as visible should be displayed to the user.

SpamControl.getCategories(context = this)

data class Category(
    val id: Int, // Id from categories database
    val category: String?, // Category's name
    val description: String?, // Category's description
    val isBlocked: Int?, // True if blocked and false if unblocked
    val regex: String?, // Category's regex, usually used to block numbers by prefix
    val icon: String?, // Category's icon for ui
    val categoryRule: String?, // Rule applied when a number matches this category
    val isVisible: Boolean, // Whether this category should be shown in the UI
    val isTrusted: Boolean // Whether numbers in this category are considered trusted
)

blockCategory: Blocks future calls from any number inside a specific spam category

SpamControl.blockCategory(context = this, categoryId = ...)

unblockCategory: Unblocks future calls from any number inside a specific spam category

SpamControl.unblockCategory(context = this, categoryId = ...)

isNumberBlocked: Returns a Boolean that corresponds if the number is blocked or not. It returns null only if the number is neither in the user’s call history nor among the numbers the user blocked or unblocked manually.

SpamControl.isNumberBlocked(context = this, number = ...)

Subscription

The subscriptionMode parameter of enableSpamControl and enableSpamControlSilently defines how call blocking relates to the client’s subscription. It is set at activation only: when the service is already on, the parameter is ignored. The SDK keeps the subscription state up to date on its own, with its recurring syncs, so a state change reaches the device without any action from the integrator, within about 24 hours. getSubscriptionMode returns the mode in force, which is persisted across process restarts.

enum class SubscriptionMode {
    FREE, // Default. Call blocking does not depend on a subscription, except for SUBSCRIPTION_REQUIRED.
    PAID, // Call blocking follows the client's SubscriptionState.
}

enum class SubscriptionState {
    ACTIVE, // Paid cycle in force. Call blocking is active.
    PENDING_PAYMENT, // Paid cycle expired. Call blocking stops and calls it would block are marked ALLOWED_PENDING_PAYMENT. Spam identification continues.
    CANCELLED, // Cancelled and the paid cycle is over. The service is turned off.
    PENDING_CANCELATION, // Cancelled but still inside the cycle already paid for. Call blocking stays on until the backend reports CANCELLED.
    SUBSCRIPTION_REQUIRED, // The client has to subscribe before using the service. The service is turned off, in both modes.
}

When the state is CANCELLED or SUBSCRIPTION_REQUIRED, the service is turned off and stays off. If a later state shows that the client subscribed again, call enableSpamControl or enableSpamControlSilently to turn it back on.

refreshSubscriptionState: Fetches the client’s subscription state from the backend, applies it and returns it. The SDK already refreshes the state recurrently on its own, so calling this method is optional. Call it only if you want a state change to reach the device within seconds instead of waiting for the next recurring sync, for example when the app comes to the foreground or opens from the deeplink received by SMS when the state changes. It is a suspend function, so call it from a coroutine. It is cheap and safe to call on every foreground. A timeout, a network failure or an unrecognized state leave the current state and call blocking untouched. It returns null without touching the network in FREE mode.

val state: SpamControl.SubscriptionState? = SpamControl.refreshSubscriptionState(context = this)

getSubscriptionState: Returns the last known SubscriptionState, without touching the network. Use PENDING_PAYMENT to decide when to show pending-payment UI. It returns null if no state was received yet. In FREE mode, the only state ever recorded is SUBSCRIPTION_REQUIRED.

val state: SpamControl.SubscriptionState? = SpamControl.getSubscriptionState(context = this)

getSubscriptionMode: Returns the current SubscriptionMode.

val mode: SpamControl.SubscriptionMode = SpamControl.getSubscriptionMode(context = this)

Migrating from 0.17.x

getNoPaymentStatus and setNoPaymentStatus were removed. Use getSubscriptionState() == SubscriptionState.PENDING_PAYMENT to know if blocking is suspended; the SDK owns that state now.
getSubscription was removed. The SDK refreshes the state on its own; use getSubscriptionState to read it and, optionally, refreshSubscriptionState to apply a change right away.
A device that ran the old subscription flow moves to PAID mode on update, and stays suspended if it was.

Minimum Android Version

Our current minSdkVersion is 24.

Required Permissions

The SDK will require the following permissions to function correctly:

INTERNET Since the block list is dynamic and needs to be downloaded from a server.
ACCESS_NETWORK_STATE To check if there is wifi or 4g connectivity before enabling the service.
READ_CONTACTS Provides access to the user’s contact list. Without this permission, it is impossible to block a call from a contact. (api 29+)
READ_CALL_LOG Provides access to the user’s call history. We use this data, like if a call was rejected or answered, as well as the call duration, to improve our spam detection.
POST_NOTIFICATIONS: So we can trigger notifications from time to time to let the user know how many blocks happened
Default dialer To allow the SDK to detect incoming calls (api 24 to 28).
Default spam app To allow the SDK to detect incoming calls (api 29+).

SDK Documentation

Activation SDK

Usage SDK

Spam Control SDK

Offers SDK

Adding the Repository

Initialization

Subscription

Migrating from 0.17.x

Minimum Android Version

Required Permissions

​Adding the Repository

​Initialization

​Subscription

​Migrating from 0.17.x

​Minimum Android Version

​Required Permissions

Adding the Repository

Initialization

Subscription

Migrating from 0.17.x

Minimum Android Version

Required Permissions