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.
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’
Determine Extension Type: (EL or Non-EL)
Depending on your build type; there are different fields required for configuration.
Generally there are three types. Extension Launchpad, Server Side Extensions, and Custom Extensions.
- Custom Extensions and Server Side Extensions should reference Non-EL sections.
- Extension Launch Pad should reference EL sections.
Don't know your build type? Ask your Client Success Manager.
NON- EL: Extension Configuration Settings
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.
- Once set the extension will stay logged in for that user until a new non-empty string is returned.
2.GET_AUTO_LOGOUT_FLAG (Optional)
Works in tandem with GET_USER_ID. When the host app sets it to true, the extension watches for a USER_ID to be empty; if both conditions are met simultaneously, the extension resets and treats the extension as logged-out. For most use cases this should always be set to false, and only be set to true if the user has explicitly asked to be logged out of the extension.
3.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.
4.GET_APP_PROFILE (Optional)
Returns the app profile the user should use. Only needed if your extension uses more than one appID, typically to support multiple countries.
- Return value: A profile string defined by Wildfire, such as 'US', 'CA', or 'MX'.
- Single appID: You can skip this. If nothing is returned, the default profile is used.
- Persistence: Once a non-default profile is returned, it stays active until a different valid profile is returned.
Extension Configuration Settings (Extension Launchpad)
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.
- Until a valid UserID is returned, 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:
Examples:
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.