🕵️‍♂️Apple ATT

This documentation is designed to help you implement the App Tracking Transparency (ATT) framework in your Natively app. This is required if your app collects data used for tracking or accesses the device's advertising identifier (IDFA).

Apple’s definition of "tracking" specifically refers to linking data collected from your app with third-party data for advertising or sharing that data with a data broker.

"Is it Tracking?" Checklist

Here is the breakdown of when you actually need to ask for tracking permissions:

Ads (AdMob, Meta, etc.): YES. If users deny, you must serve non-personalized ads (or no ads) and stop sending the IDFA.
Third-Party Analytics (Meta Pixel, Google Analytics): YES. If these tools track the user's behavior across other websites or apps to build a profile, you must ask.
First-Party Analytics: NO. If you are just tracking what the user does inside your app to improve the UI (e.g., "User clicked Button A"), and you aren't sharing that with others for ad-targeting, ATT is technically not required.
Authentication/Fraud: NO. You don't need ATT for strictly functional things like keeping a user logged in or preventing bot attacks.

If AdMob or Analytics features are enabled in your Natively dashboard, the App Tracking Transparency (ATT) dialog will be triggered automatically on the first app launch to ensure compliance with Apple’s privacy guidelines.

Web-Based Analytics: Even if you use a web-based tracking solution, you still need to implement Apple ATT if that web solution collects identifiers for tracking.

Natively Dashboard Setup

Navigate to Features > Apple ATT in your app's dashboard.
Enable Apple ATT and provide the Permission Description text. The Permission Description is a mandatory string that Apple displays to the user explaining why you are requesting tracking permission.
Click Save.

Permission Description: Be honest and clear. Apple frequently rejects apps that provide vague descriptions like "We need this to improve the app." Instead, use: "We use your data to provide personalized advertisements that are relevant to your interests."

You must rebuild your application for these changes to take effect.

Implementation

Choose your integration method below: Bubble.io Plugin (No-Code) or JavaScript SDK (Code).

Initialization

Check Plugin

Before starting, verify if the Natively plugin is already installed in your Bubble project.

Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
Check Installed Plugins: Look through your list of installed plugins for "Natively iOS & Android app builder".
- If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

If it is NOT installed: Click the + Add plugins button , search for "Natively", and click Install.

Check SDK

Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.

Open your project's main HTML file (or header settings) and look for the Natively script tag inside the <head> section.
Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., @2.25.2) .

<head>
  <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/[email protected]/natively-frontend.min.js"></script>
</head>

Setup logic

Drag the Natively - ATT element onto your page.

This element must be set to Visible on page load to initialize correctly. It should be placed directly on the page root and not inside hidden containers, such as Popups, Floating Groups, Group Focus elements, or Repeating Groups. To hide the element from your UI, you may set its dimensions to 0x0 px.

Element Logic (Events, States, & Actions)

Use the following data points to build your logic.

Events:
- ATT is authorized: Fires whenever the ATT is successfully authorized.
- ATT is not authorized: Fires whenever the ATT is denied.
States:
- Status (Text): Returns the permission status: authorized | denied | notDetermined | restricted | notSupported .
- isAuthorized (Yes/No): Returns yes if permission is authorized.
Actions:
- Show ATT: Triggers the native system dialog using the "Permission description" defined in your dashboard.
- Get ATT's Status: Manually refreshes the Status and isAuthorized states. Useful if you need to ensure the current status before a specific workflow.

// ============================================================================
// NATIVELY APP TRACKING TRANSPARENCY (ATT) - DOCUMENTATION & EXAMPLES
// ============================================================================
// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// natively.attGetStatus(callback); 
//    - Retrieves the current tracking authorization status.
//    - Does NOT trigger a popup. Use this to check status.
//
// natively.attShowPopup(callback); 
//    - Triggers the native iOS ATT permission dialog.
//    - Note: This popup will only appear ONCE per app installation. 
//    - If the user has already decided, the callback returns the existing status 
//      immediately.


// --- ATT Implementation. Start ---

/**
 * 1. DEFINE THE CALLBACK
 * This function handles the response object returned by the Natively SDK.
 */
const handleAttResponse = (resp) => {
    // resp.status (string): 'authorized', 'denied', 'notDetermined', 'restricted', 
    // or 'notSupported'
    // resp.isAuthorized (boolean): true if authorized, false otherwise
    
    console.log("ATT Status:", resp.status);
    console.log("Is Authorized:", resp.isAuthorized);
    
    if (resp.isAuthorized) {
        // Handle logic for authorized users (e.g., initialize tracking SDKs)
        console.log("User granted tracking permission.");
    } else {
        // Handle logic for non-authorized users
        console.log("User declined or restricted tracking.");
    }
};

/**
 * 2. CHECK STATUS
 * Call this when the app or page loads to determine current permissions.
 */
function checkStatus() {
    if (window.natively) {
        natively.attGetStatus(handleAttResponse);
    } 
}

/**
 * 3. REQUEST PERMISSION
 * Call this when the user interacts with a UI element (like an 'Accept' button).
 */
function requestPermission() {
    if (window.natively) {
        natively.attShowPopup(handleAttResponse);
    }
}

// --- ATT Implementation. End ---


// ============================================================================
// UNDERSTANDING THE RESPONSE
// ============================================================================
/**
 * The 'status' string returned in the callback can be:
 * * 'authorized'    -> User granted permission. 
 * (isAuthorized: true)
 * * 'denied'        -> User explicitly denied permission. 
 * (isAuthorized: false)
 * * 'notDetermined' -> User hasn't seen the prompt yet. 
 * (isAuthorized: false)
 * * 'restricted'    -> Tracking is restricted at the OS level (e.g., parental controls). 
 * (isAuthorized: false)
 * * 'notSupported'   -> The device or OS version does not support ATT (e.g., Android or old iOS).
 * (isAuthorized: false)
 */

Auto-Prompt vs. Manual

The behavior of the ATT popup changes depending on which other features (like Analytics or AdMob) are enabled in your app.

ATT Only

❌ No

✅ Supported

ATT + Analytics (or AdMob)

✅ Yes

❌ Not Supported

ATT + Analytics + AdMob

✅ Yes

❌ Not Supported

Analytics + AdMob (No ATT)

✅ Yes

❌ Not Supported

PreviousAdmob NextApp Storage

Last updated 21 hours ago

// ============================================================================ // NATIVELY APP TRACKING TRANSPARENCY (ATT) - DOCUMENTATION & EXAMPLES // ============================================================================ // ============================================================================ // ALL AVAILABLE METHODS // ============================================================================ // natively.attGetStatus(callback); // - Retrieves the current tracking authorization status. // - Does NOT trigger a popup. Use this to check status. // // natively.attShowPopup(callback); // - Triggers the native iOS ATT permission dialog. // - Note: This popup will only appear ONCE per app installation. // - If the user has already decided, the callback returns the existing status // immediately. // --- ATT Implementation. Start --- /** * 1. DEFINE THE CALLBACK * This function handles the response object returned by the Natively SDK. */ const handleAttResponse = (resp) => { // resp.status (string): 'authorized', 'denied', 'notDetermined', 'restricted', // or 'notSupported' // resp.isAuthorized (boolean): true if authorized, false otherwise console.log("ATT Status:", resp.status); console.log("Is Authorized:", resp.isAuthorized); if (resp.isAuthorized) { // Handle logic for authorized users (e.g., initialize tracking SDKs) console.log("User granted tracking permission."); } else { // Handle logic for non-authorized users console.log("User declined or restricted tracking."); } }; /** * 2. CHECK STATUS * Call this when the app or page loads to determine current permissions. */ function checkStatus() { if (window.natively) { natively.attGetStatus(handleAttResponse); } } /** * 3. REQUEST PERMISSION * Call this when the user interacts with a UI element (like an 'Accept' button). */ function requestPermission() { if (window.natively) { natively.attShowPopup(handleAttResponse); } } // --- ATT Implementation. End --- // ============================================================================ // UNDERSTANDING THE RESPONSE // ============================================================================ /** * The 'status' string returned in the callback can be: * * 'authorized' -> User granted permission. * (isAuthorized: true) * * 'denied' -> User explicitly denied permission. * (isAuthorized: false) * * 'notDetermined' -> User hasn't seen the prompt yet. * (isAuthorized: false) * * 'restricted' -> Tracking is restricted at the OS level (e.g., parental controls). * (isAuthorized: false) * * 'notSupported' -> The device or OS version does not support ATT (e.g., Android or old iOS). * (isAuthorized: false) */

hashtag"Is it Tracking?" Checklist

hashtagNatively Dashboard Setup

hashtagImplementation

hashtagInitialization

hashtagSetup logic

hashtagAuto-Prompt vs. Manual

"Is it Tracking?" Checklist

Natively Dashboard Setup

Implementation

Initialization

Setup logic

Auto-Prompt vs. Manual