How to implement the Mobile Safari Extension

Overview

This will be a brief walkthrough for importing our iOS Safari Extension into an existing iOS App. After Wildfire builds the extension to agreed specifications we will provide an Xcode project that includes an example host app and the Safari Extension App. This can be used for testing the extension without requiring the extension to be added into your project.

If you are interested in the Wildfire's turn-key Mobile Safari Extension please [contact your client success representative.](/content/contact-us "contact your client success representative."/index.html)

Add a new target in the destination project

We will start by opening up your existing Xcode project and create a new Target.

File > New > Target...

Select "Safari Extension" from the list of iOS targets.

Name your new target, this can follow your conventions and be anything.

Remove the template files

Next, we will remove most of the new files created and replace them with the ones from the extension project.

Delete all of the files within the Resources Directory and the SafariWebExtensionHandler

Add the extension files to your project

Select your project from the navigator in Xcode and Select the target for your extension > then select Build Phases.

Expand the "Copy Bundle Resources" section.

• Click the plus sign and select "Add Other...".
• Navigate to {Your Extension}/xcode-project/iOS (Extension)/Resources.
• Select the manifest.json, _locales, and source directories.
• Click "Open".
• Ensure "Copy items if needed" and "Create folder references" are checked.
• Click "Finish".

The files you just added will be located at the root level of your app in Xcode.

• Move these three files to the {Your App}/{Extension Name}/Resources directory in the Project Navigator in Xcode.

Navigate back to your-extension/xcode-project/iOS (Extension) and:

• Move the Info.plist, extensionLaunchpad.entitlements, and SafariWebExtensionHandler.swift files to the {Your App}/{Extension Name}/ directory inside your project in Xcode.

• Uncheck the {Extension Name} target and click "Finish".

• Note: If you do this outside of Xcode, Xcode may add these to your targets automatically; if this happens, you’ll need to remove these from the targets.

• Select your project again and go to Build Phases

• Select Compile Sources, click the + and select SafariWebExtensionHandler.swift file you added earlier in the new window and click ‘Add’

Extension Configuration Settings

The host application can provide configuration settings to control extension behavior and manage user attribution. These values are passed from the native host app to the JavaScript context of the extension via SafariWebExtensionHandler.swift.

1. GET_USER_ID (Required)

A unique identifier generated by the host application to identify the current user.

• If the user is not yet authenticated, return an empty string.
• When unset, the extension will operate in a logged-out state.

2. IS_EXTENSION_ENABLED (Required)

A boolean flag that enables or disables the extension.

• Must be set to true for the extension to function.
• If set to false, the extension will remain inactive.

3. IS_COUPON_ENABLED (Required)

A boolean flag that controls the availability of the Couponator feature.

• Must be true for users to see applicable coupons on eligible checkout pages.

4. GET_SPLIT_AMOUNT (Required)

A float value between 0 and 1 that determines the user's share of transaction earnings.

This value impacts how earning visuals are displayed:

5. GET_LAST_LINK_TIMESTAMP (Optional)

A Unix timestamp indicating the last time an affiliate link was presented within the host app.

• If provided, this prevents the extension from displaying a Merchant Engagement Alert (EMA) on the next website load.

Note: Configuration values can either be hard-coded into SafariWebExtensionHandler.swift or set using an App Group shared between the host app and the extension.

Success

You have successfully added the extension into your app. It will automatically be installed when the project is run on either the simulator or a physical device.

Note__: Extensions must be enabled in Safari before Safari will allow them to launch. This is done by selecting 'Manage Extensions' from the pop-up menu within Safari.

Updated 11 Jun 2026