undergroundcreative/cordova-plugin-idfa

Cordova plugin to get Advertising ID (IDFA or AAID)

Cordova plugin for getting Advertising ID (IDFA or AAID)

Index

• Supported Platforms
• Installation
• API
• Example

Supported Platforms

• iOS
• Android

Installation

$ cordova plugin add cordova-plugin-idfa

Use variable ANDROID_PLAY_ADID_VERSION to override dependency version on Android:

$ cordova plugin add cordova-plugin-idfa --variable ANDROID_PLAY_ADID_VERSION='16.+'

API

The API is available on the cordova.plugins.idfa global object.

getInfo()

Returns a Promise<object> with the following fields:

• trackingLimited: boolean - Whether usage of advertising id is allowed by user.
• idfa: string (iOS only) - Identifier for advertisers.
• trackingPermission (iOS 14+ only): number Tracking permission status, available on iOS 14+ devices.
• aaid: string (Android only) - Android advertising ID.

requestPermission()

(iOS only) A one-time request to authorize or deny access to app-related data that can be used for tracking the user or the device. See Apple's API docs for more info on the dialog presented to the user. Available only for iOS 14+ devices.

Returns a Promise<number>. On devices with iOS < 14 the method will return a rejected promise.

Note: You should make sure to set the NSUserTrackingUsageDescription key in your app's Information Property List file, otherwise your app will crash when you use this API. You can do it with the following code in your Cordova project's config.xml:

<platform name="ios">
    <edit-config target="NSUserTrackingUsageDescription" file="*-Info.plist" mode="merge">
        <string>My tracking usage description</string>
    </edit-config>
</platform>

Tracking Permission Values

The tracking permission values are numbers returned by getInfo() and requestPermission(). The possible values are stored in constants on the plugin object. See the example on how to use them.

For the meaning of the values see the tracking transparency API docs:

Constant	Value	Description
TRACKING_PERMISSION_NOT_DETERMINED	0	User has not yet received an authorization request to authorize access to IDFA
TRACKING_PERMISSION_RESTRICTED	1	User restricted the value returned if authorization to access IDFA
TRACKING_PERMISSION_DENIED	2	The value returned if the user denies authorization to access IDFA
TRACKING_PERMISSION_AUTHORIZED	3	The value returned if the user authorizes access to IDFA

Example

const idfaPlugin = cordova.plugins.idfa;

idfaPlugin.getInfo()
    .then(info => {
        if (!info.trackingLimited) {
            return info.idfa || info.aaid;
        } else if (info.trackingPermission === idfaPlugin.TRACKING_PERMISSION_NOT_DETERMINED) {
            return idfaPlugin.requestPermission().then(result => {
                if (result === idfaPlugin.TRACKING_PERMISSION_AUTHORIZED) {
                    return idfaPlugin.getInfo().then(info => {
                        return info.idfa || info.aaid;
                    });
                }
            });
        }
    })
    .then(idfaOrAaid => {
        if (idfaOrAaid) {
            console.log(idfaOrAaid);
        }
    });