# How to use it ?
**How to use Appconsent Instance ?**
Here is a list of the most commonly used methods.
### Knowing whether the user has given consent
```kotlin
appconsent.isConsentGiven()
```
Returns `true` if consent has been given, `false` otherwise.
{% hint style="danger" %}
**WARNING**
Please note that this only refers to whether the user **has confirmed a choice** and not whether they have accepted or refused their consent.
{% endhint %}
### CMP display modes
There are three display modes:
1. The first mode is **ONLY** executed if user consent is required.
2. The second mode allows your users to view/modify their consent with direct access to layer 1 (*often used from your settings screen to display your user's privacy policy*) - layer 1 corresponds to the main display of your notice. The window will be displayed **ALL THE TIME**.\
\&#xNAN;***This does not take into account the GDPR regulations of your users' geographic location.***
3. The last one is actually equivalent to the second one, except that the user has direct access to layer 2. This screen allows you to configure your different purposes/stacks in detail, as well as your partners. The window will be displayed **ALL THE TIME**.\
\&#xNAN;***This does not take into account the GDPR regulations of your users' geographic location.***
{% hint style="info" %}
**NOTE**
By default, this “**presentNotice**” method attempts to display the CMP. It attempts to do so because, depending on the region of your users, it will follow its controls and display the CMP only if necessary.\
\
It will also be displayed if user consent has not yet been given or if it needs to be renewed.
{% endhint %}
```kotlin
appconsent.presentNotice() // Conditional — displays only if GDPR applies, and consent is missing or no longer valid
appconsent.displayLayer1() // GDPR-agnostic — always displays the first consent layer
appconsent.displayLayer2() // GDPR-agnostic — always displays the second consent layer
```
### **GCM Status**
{% hint style="info" %}
**INFO**
This method shows the **current** status of GCMv2 (Google Consent Mode V2).
Before calling up this method, it's best to make sure that the user has **already given his consent** and that it's up to date, and that the CMP doesn't need to be redisplayed.
Otherwise :
* either the saved value of the **old consent** will be returned
* or the **default values** of your FirebaseAnalytics AndroidManifest configuration will be returned
[Set the default consent state from google documentation](https://developers.google.com/tag-platform/security/guides/app-consent?consentmode=advanced\&platform=android#default-consent)
{% endhint %}
```kotlin
appconsent.getGCMState()
```
Return `ACGcmState`
Data model representing the state of GCMv2 (Google Consent Mode v2)
This will allow you to define consent from your Firebase Analytics instance.
`isAnalyticsStorageGranted`, indicates whether the user has given consent for **FirebaseAnalytics.ConsentType#ANALYTICS\_STORAGE**
`isAdStorageGranted`, indicates whether the user has given consent for **FirebaseAnalytics.ConsentType#AD\_STORAGE**
`isAdUserDataGranted`, indicates whether the user has given consent for **FirebaseAnalytics.ConsentType#AD\_USER\_DATA**
`isAdPersonalizationGranted`, indicates whether the user has given consent for **FirebaseAnalytics.ConsentType#AD\_PERSONALIZATION**
[FirebaseAnalytics.ConsentType](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.ConsentType)
### **Check for update**
This method allows you to check from our servers whether your Notice has been updated since it was last displayed on your user's device.
{% hint style="info" %}
**INFO**
The method will return true if you have modified the Source and/or Notice from your dashboard and, if and **only if**, you have configured your Notice to update for all your users.
{% endhint %}
{% hint style="danger" %}
**ATTENTION**
This method can only be used once within a **predefined time period**. This allows you to force a first network call to make sure your users are up to date. The next calls to this method will use the cache of the previous response or attempt a network call if the previous one was in error.
{% endhint %}
```kotlin
appconsent.checkForUpdate({ needToUpdate: Boolean ->
if (needToUpdate) {
/*
The Notice has been updated and must be resubmitted to your users.
We recommend clearing the existing consent locally, then letting your
app's natural flow re-trigger the CMP (e.g. via presentNotice() called
at your usual checkpoint, as set up earlier in your app lifecycle).
Clearing the consent locally avoids an unnecessary network call on the
next launch to check whether the Notice has been updated, since no
consent will be present on the user's device.
*/
appconsent.askToClearConsent(
onSuccess = { },
onError = { },
)
// Do not call presentNotice() directly here.
// Instead, redirect the user to the appropriate screen in your app
// where the CMP will be displayed as part of the normal user journey.
} else {
/*
The Notice has not changed since the last verification — no changes
have been made on your end, and no internal updates have been applied
(such as a vendor list update).
No action is required.
*/
}
}) { _: Throwable? ->
// An error occurred while checking for Notice updates.
}
```
## Using AppConsent's more specific methods
Here's a list of methods that could be useful if you want to go further in tracking user consent.
### **IAB Purpose X Allowed**
```kotlin
appconsent.isIabPurposeAllowed(1)
```
Returns `true` if the purpose with `id = 1` is authorized, `false` otherwise. The `id` to pass is the `iabId` of your purpose.
### IAB Purposes Allowed
```kotlin
appconsent.iabPurposeIdsAllowed() : List
```
Returns a list of integers representing the IDs of **accepted** purposes **ONLY**.
### **IAB Feature X Allowed**
```kotlin
appconsent.isIabFeatureAllowed(1)
```
Returns `true` if the feature with `id = 1` is authorized, `false` otherwise. The `id` to pass is the `iabFeatureId` of your feature.
### IAB Features Allowed
```kotlin
appconsent.iabFeatureIdsAllowed() : List
```
Returns a list of integers representing the IDs of **accepted** features **ONLY**.
### **IAB Special Feature X Allowed**
```kotlin
appconsent.isIabSpecialFeatureAllowed(1)
```
Returns `true` if the special feature with `id = 1` is authorized, `false` otherwise. The `id` to pass is the `iabSpecialFeatureId` of your special feature.
### IAB Special Features Allowed
```kotlin
appconsent.iabSpecialFeatureIdsAllowed() : List
```
Returns a list of integers representing the IDs of **accepted** special features **ONLY**.
### **IAB Special Purpose X Allowed**
```kotlin
appconsent.isIabSpecialPurposeAllowed(1)
```
Returns `true` if the special purpose with `id = 1` is authorized, `false` otherwise. The `id` to pass is the `iabSpecialPurposeId` of your special purpose.
### IAB Special Purposes Allowed
```kotlin
appconsent.iabSpecialPurposeIdsAllowed() : List
```
Returns a list of integers representing the IDs of **accepted** special purposes **ONLY**.
### **Stack X Allowed**
```kotlin
appconsent.isIabStacksAllowed(1)
```
Returns `true` if the stack with `id = 1` is authorized, `false` otherwise. The `id` to pass is the `iabStackId` of your stack.
### IAB Stacks Allowed
```kotlin
appconsent.iabStacksIdsAllowed() : List
```
Returns a list of integers representing the IDs of **accepted** stack **ONLY**.
### **Vendor X Allowed**
```kotlin
appconsent.isIabVendorAllowed(1)
```
Returns `true` if the vendor with `id = 1` is authorized, `false` otherwise. The `id` to pass is the `iabVendorId` of your stack.
### IAB Vendors Allowed
```kotlin
appconsent.iabVendorsAllowed() : List
```
Returns a list of integers representing the IDs of **accepted** vendors **ONLY**.
### **Extra Vendor X Allowed**
```kotlin
appconsent.isExtraVendorAllowed("abc123")
```
Returns `true` if the extra vendor with `id = "abc123"` is authorized, `false` otherwise.
### Extra Vendors **Allowed**
```kotlin
appconsent.extraVendorsAllowed() : List
```
Returns a list of string representing the IDs of **accepted** extra vendors **ONLY**.
### **Extra Purpose X Allowed**
```kotlin
appconsent.isExtraPurposeAllowed("abc123")
```
Returns `true` if the extra purpose with `id = "abc123"` is authorized, `false` otherwise.
### Extra **Purpose** **Allowed**
```kotlin
appconsent.extraPurposeIdsAllowed() : List
```
Returns a list of string representing the IDs of **accepted** extra purpose **ONLY**.
### Purposes list
```kotlin
appconsent.getPurposes() : List
```
Returns a list of all purposes in your source with the user-defined status `ACConsentable`.
```kotlin
data class ACConsentable(
override val id: String,
override val type: String,
override val status: String,
override val additionalInfo: Map,
)
```
In this example, the `id` is that of the purpose, the `type` is PURPOSE, the `status` is an integer in string form (see `ACConsentableStatus`), and `additionalInfo` will allow us to retrieve the latest updates from the IAB in the future if it adds any.\
It's time for our SDK to offer the new entry.
### Purposes list by status
```kotlin
appconsent.getPurposesByStatus(status: ACConsentableStatus) : List
```
Returns a list of all purposes in your source filtered by the status you pass as a parameter.
### Features list
```kotlin
appconsent.getFeatures() : List
```
Returns a list of all features in your source with the user-defined status `ACConsentable`.
### Features list by status
```kotlin
appconsent.getFeaturesByStatus(status: ACConsentableStatus) : List
```
Returns a list of all features in your source filtered by the status you pass as a parameter.
### Special Purpose list
```kotlin
appconsent.getSpecialPurposes() : List
```
Returns a list of all special features in your source with the user-defined status `ACConsentable`.
### Special Purpose list by status
```kotlin
appconsent.getSpecialPurposesByStatus(status: ACConsentableStatus) : List
```
Returns a list of all special purpose in your source filtered by the status you pass as a parameter.
### Special Feature list
```kotlin
appconsent.getSpecialFeatures() : List
```
Returns a list of all special features in your source with the user-defined status `ACConsentable`.
### List de Special Feature par status
```kotlin
appconsent.getSpecialFeaturesByStatus(status: ACConsentableStatus) : List
```
Returns a list of all special features in your source filtered by the status you pass as a parameter.
### Extra Purpose list
```kotlin
appconsent.getExtraPurposes() : List
```
Returns a list of all extra purpose in your source with the user-defined status `ACConsentable`.
### Extra Purpose list by status
```kotlin
appconsent.getExtraPurposesByStatus(status: ACConsentableStatus) : List
```
Returns a list of all extra purpose in your source filtered by the status you pass as a parameter.
### Stack list
```kotlin
appconsent.getStacks() : List
```
Returns a list of all stack in your source with the user-defined status `ACConsentable`.
### Stack list par status
```kotlin
appconsent.getStacksByStatus(status: ACConsentableStatus) : List
```
Returns a list of all stack in your source filtered by the status you pass as a parameter.
### Extra Vendors list
```kotlin
appconsent.getExtraVendors() : List
```
Returns a list of all extra vendors in your source with the user-defined status `ACExtraVendor`.
```kotlin
data class ACExtraVendor(
override val id: String,
override val type: String,
override val status: String,
override val additionalInfo: Map,
)
```
### Extra Vendors list by status
```kotlin
appconsent.getExtraVendorsByStatus(status: ACConsentableStatus) : List
```
Returns a list of all extra vendors in your source filtered by the status you pass as a parameter.
### Is the user's consent mixed?
```kotlin
appconsent.isConsentMixed()
```
Returns `true` if all user consent is mixed. That is, if some consent items have been accepted and others rejected.
### Did the user accept everything?
```kotlin
appConsent.isAllAllowed()
```
Returns `true` if all consentables, stacks, and vendors are accepted. Returns `false` if at least one of them is not accepted.
### Did the user refuse everything?
```kotlin
appConsent.isAllDisallowed()
```
Returns `true` if all consentables, stacks, and vendors are rejected. Returns `false` if at least one of them is not rejected.
### Define the status of consentable items
```kotlin
appconsent.setConsentableConsents(
newConsentableConsents: ACConsentOverride,
onSuccess: () -> Unit,
onError: () -> Unit,
)
```
Define the status of the new consent and save it.
The `ACConsentOverride` object allows you to modify any consentable item as many times as you want in a single operation. It provides a list of consentable items to be modified, such as purposes, stacks, vendors, etc.
Each status is constructed in the following form using the `ACConsentStatus` object.\
The latter takes the following parameters:
* **id**: The ID of the consentable you want to modify (as a string)
* **status**: the new status you want to “redefine” (as a boolean)
* `true`: **ALLOWED**
* `false`: **DISALLOWED**
* **legintStatus**: the new legitimate status you want to “redefine” (as a boolean)
* `true`: **ALLOWED**
* `false`: **DISALLOWED**
`onSuccess`**:** is the callback that will be called if consent has been successfully modified and saved
`onError`**:** is the callback that will be called if an error occurred during the modification
### **Delete the consent**
Completely resets the user's consent status.
```kotlin
appConsent.askToClearConsent(
onSuccess: () -> Unit,
onError: () -> Unit,
)
```
{% hint style="info" %}
This action is asynchronous.
{% endhint %}
This action deletes all locally stored consent information for the user\
(e.g., choices for vendors, purposes, etc.). After this method is called, the SDK\
will consider the user as not having provided consent yet. The consent notice (CMP) will be displayed again the next time an action requiring consent is performed.
{% hint style="info" %}
**@param** onSuccess A callback invoked upon successful update.\
\&#xNAN;**@param** onError A callback invoked if the update fails.
{% endhint %}
### Define your external IDs
```kotlin
val ids = mapOf("customPersonalId" to "abze23", "otherData" to "{\"name\": \"test\"}")
appConsent.askToSetExternalIds(
externalIds = ids,
onSuccess = { },
onError = { errorMessage -> }
)
```
Allows you to set your external credentials while saving them on our servers.
### Retrieve your external IDs
Retrieve your previously saved external IDs
```kotlin
appConsent.askToGetExternalIds(
onSuccess = { externalIds -> },
onError = { }
)
```
### Define your external IDs locally
```kotlin
val ids = mapOf("customPersonalId" to "abze23", "otherData" to "{\"name\": \"test\"}")
appConsent.setLocalExternalIds(
externalIds = ids
)
```
Allows you to save your external credentials **LOCALLY**, which **will be sent** to the server when the user gives their consent.
### Retrieve your local external IDs
```kotlin
appConsent.getLocalExternalIds() : Map
```
Retrieve your externally saved IDs locally
### Get User ID
```kotlin
appconsent.getUserId() : String
```
Retrieves the user ID used for consent
### Find out if the user has restricted the use of their advertising ID
```kotlin
appconsent.isLimitedTrackingEnabled() : Boolean
```
`true` if the user ID is restricted, `false` otherwise
### Knowing if your user is subject to consent
```kotlin
appconsent.isSubjectToGDPR() : Boolean?
```
Returns `true` if your user is subject to consent, `false` if the user is not, `null` if the information is not yet known by our SDK.
### Know the overall status of purposes
```kotlin
appconsent.getPurposesStatus() : ACConsentableStatus
```
Allows you to quickly see the status of all purposes for your source, following user consent.
```kotlin
enum class ACConsentableStatus{
DISALLOWED,
PENDING,
ALLOWED,
MIXED,
UNKNOWN,
}
```
### Know the overall status of stacks
```kotlin
appconsent.getStacksStatus() : ACConsentableStatus
```
Allows you to quickly see the status of all stacks for your source, following user consent.
### Know the overall status of vendors
```kotlin
appconsent.getVendorsStatus() : ACConsentableStatus
```
Allows you to quickly see the status of all vendors for your source, following user consent.
### Know the overall status of user's consent
```kotlin
appconsent.getConsentStatus() : ACConsentableStatus
```
Provides a quick overview of the status of user consent.
Quickly see whether the user has **ACCEPTED ALL**, **REFUSED ALL**, **MIXED**, **PENDING**, or **UNKNOWN**.
### Define user consent to REFUSE ALL
```kotlin
appconsent.forceDenyAll(onSuccess: () -> Unit, onError: () -> Unit)
```
Allows you to confirm the “**DECLINE ALL**” action. This action behaves in the same way as if the CMP were displayed to your users and they clicked on the “**decline all**” button.
A new consent will be applied and saved.
### Define user consent to ACCEPT ALL
```kotlin
appconsent.forceAcceptAll(onSuccess: () -> Unit, onError: () -> Unit)
```
Allows you to validate the “**ACCEPT ALL**” action. This action behaves in the same way as if the CMP were displayed to your users and they clicked on the “**accept all**” button.
A new consent will be applied and saved.
### Save your floating purpose
```kotlin
appconsent.saveFloatingPurpose(
floatingPurposesStatus: Map,
onSuccess: () -> Unit,
onError: () -> Unit
)
```
If you have defined floating purposes in your source, define their identifiers and user statuses as parameters so that they are taken into account and saved.
### Find out if any of your floating purposes need to be updated
```kotlin
appconsent.isFloatingNeedUpdate(
floatingPurposeId: String,
onSuccess: (isFloatingNeedToUpdate: Boolean) -> Unit,
onError: () -> Unit
)
```
If you have defined floating purposes in your source, this method will check whether the one passed as a parameter has been updated since then.
`onSuccess`: will return `true` or `false` depending on
### Forces the saving of your external credentials
```kotlin
appconsent.saveExternalIds(
onSuccess: () -> Unit,
onError: () -> Unit
)
```
Allows you to save your external credentials on the server.
## (Bonus) Retrieve your consents
Your consents are saved in `SharedPreferences` of your application. To know more about keys used to save your consents, please refer to the [**IAB documentation**](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#in-app-details).
We also provide an additional key for Google Additionnal Consent `IABTCF_AddtlConsent` returning a String.
