# Implementing Authentication for the Mobile Safari Extension

## Overview

The authentication flow for the Wildfire Mobile Safari Extension is unique because **the extension itself does not perform authentication**. Unlike desktop browser extensions that might use an OAuth web flow, iOS architecture prevents Safari extensions from directly accessing the native Host App's internal data or APIs. To overcome this, **authentication relies entirely on a shared data layer** between your native iOS app and the Safari extension.

1. **Step 1: Authenticate the User in Your Native App**  
   Because the extension does not handle logins, your user will simply log into your existing iOS application (the Host App) using your standard authentication methods.

2. **Step 2: Establish a Shared Resource**  
   To pass the user's identity from your Host App to the Safari extension, your iOS development team must set up a shared data store. To do this, **you will need to enable the "App Groups" entitlement** in Xcode, which allows your Host App and the extension target to securely share UserDefaults.

3. **Step 3: Write the User Identifier to the Shared Resource**  
   Once the user successfully authenticates in your Host App, your app needs to generate or retrieve their unique Anonymized User Identifier (ideally a UUID). **The Host App must then write this user ID into the shared App Group resource**.

4. **Step 4: Configure the Native Bridge (SafariWebExtensionHandler.swift)**  
   Wildfire provides a native Swift bridge file (SafariWebExtensionHandler.swift) that sits between Safari and your app. You will need to configure this handler to read from your shared App Group.  
   When Safari activates the extension, the JavaScript extension requests the user ID from this Swift handler. The handler must be configured to pass the user's identifier into the **GET_USER_ID** configuration setting.  
   Once the JavaScript extension receives this ID, it will automatically append it to the tracking links (as the Tracking Code or tc parameter) to ensure all merchant purchases are attributed to the correct user.

5. **Handling Logged-Out States**  
   If the user logs out of your native app, your app should clear the user ID from the shared resource. If the user is not authenticated, **the GET_USER_ID setting should simply return an empty string**. When this value is empty, the Safari extension will automatically operate in a logged-out state.

**Summary of the Data Flow:**  
1. User logs into the partner's Host App.  
2. Host App writes the user's unique ID to an App Group/User Defaults.  
3. Safari activates the extension, which requests the user ID from the SafariWebExtensionHandler.  
4. The handler reads the shared resource and passes the ID to the extension via GET_USER_ID.  
5. The extension uses the ID to track purchases and attribute cash back.

Updated 17 Jun 2026