Shopping Portal Mobile Embedded Experience: Technical Implementation Guide

31 min

Shopping Portal Shopping Portal

Mobile Embedded Integration Guide
Technical reference for partners embedding the Shopping Portal as a WebView within a native mobile application.

1. Introduction 1. Introduction

The Shopping Portal is a web-based marketplace where your users can discover cashback offers and coupon savings from affiliate merchants. When a user clicks through to a merchant from the portal, the resulting purchase is tracked via affiliate links, and the user earns cashback on qualifying transactions.

This guide covers the embedded WebView integration model, where the Shopping Portal lives entirely inside your native mobile app. This is Wildfire’s recommended approach because it provides the highest level of control over the user experience and, critically, over affiliate attribution — the mechanism that connects a user’s click to their eventual purchase and cashback earnings.

An alternative option, the Browser Click-Out model, is summarized at the end of this document for partners where speed to market or limited engineering resources make a fully embedded approach impractical.

2. The Post-Click Experience: The Most Important Decision 2. The Post-Click Experience: The Most Important Decision

Before diving into implementation details, every partner needs to make a fundamental UX and technical decision: what happens when a user taps a merchant link inside the portal?

There are two options:

• In-WebView (Recommended): The merchant’s website opens inside the same WebView that hosts the portal. The user stays within your app throughout their entire shopping journey, from browsing offers through completing a purchase.
• Browser Click-Out: The merchant link opens in the user’s default mobile browser (Safari, Chrome, etc.). The user leaves your app to shop and must manually return afterward.

Why This Matters: Affiliate Attribution Why This Matters: Affiliate Attribution

Cashback earnings depend on an unbroken affiliate attribution chain. When a user clicks a merchant link in the portal, the following happens:

1. The click is routed through one or more affiliate network redirect URLs.
2. The affiliate network drops a tracking cookie in the user’s browser or WebView.
3. When the user completes a purchase on the merchant’s site, the merchant’s conversion pixel reads that cookie to attribute the sale back to the affiliate click.
4. The attributed sale generates a commission, which funds the user’s cashback.

If any step in this chain is interrupted — a redirect is intercepted, a cookie is blocked, or a tracking parameter is stripped — the purchase cannot be attributed and the user will not receive cashback.

Comparison: In-WebView vs. Browser Click-Out Comparison: In-WebView vs. Browser Click-Out

Our Recommendation Our Recommendation

Use the in-WebView post-click model unless you have a specific reason not to. We have validated this approach with existing partners, and it provides the most reliable attribution and the best user experience. The remainder of this guide assumes the in-WebView model unless otherwise noted.

If you choose browser click-out, please discuss the tradeoffs with your Client Success Manager before proceeding. We can help you understand the attribution impact based on your user base and merchant mix.

3. WebView Setup 3. WebView Setup

The Shopping Portal is delivered as a responsive web application that your app hosts inside a WebView. Your app provides the native shell — the header, navigation chrome, status bar handling, and safe-area insets — while the portal supplies the content.

3.1 Required WebView Capabilities 3.1 Required WebView Capabilities

The WebView hosting the portal must have the following capabilities enabled:

• JavaScript execution. The portal is a JavaScript-driven single-page application. It will not function without JS enabled.
• Cookie support (first-party and third-party). Affiliate tracking depends on cookies persisting across page loads and redirects within the WebView. On iOS, ensure that the WKWebView configuration does not restrict cookie storage. On Android, enable third-party cookies on the WebView instance explicitly.
• Local storage and session persistence. The portal uses local storage for user preferences and session data. The WebView’s data store should persist across app sessions — clearing it will log the user out and disrupt any in-progress shopping activity.
• Popup and new-window handling. Some merchant sites open authentication or payment flows in new windows. Your WebView must handle window.open() requests, either by opening them in a child WebView or by routing them to the system browser. Do not silently suppress them.

3.2 Platform-Specific Notes 3.2 Platform-Specific Notes

iOS (WKWebView) iOS (WKWebView)

• Use a persistent WKWebsiteDataStore (not the non-persistent variant) so cookies and local storage survive between sessions.
• Set the WKWebViewConfiguration’s processPool to a shared instance if you need cookie sharing across multiple WebViews.
• Review your app’s App Transport Security (ATS) settings. Merchant redirect chains may include non-HTTPS hops that ATS would block by default.
• Configure your WKUIDelegate to handle new-window requests from the portal and route them to the appropriate destination.

Android (WebView) Android (WebView)

• Call CookieManager.getInstance().setAcceptThirdPartyCookies(webView, true) on the WebView instance. Without this, third-party affiliate cookies will be silently dropped on Android 5.0+.
• Enable DOM storage via WebSettings.setDomStorageEnabled(true).
• If your app uses multiple WebView instances, ensure CookieManager is synced across them.
• Configure your WebChromeClient to handle new-window requests from the portal and route them to the appropriate destination.

React Native (react-native-webview) React Native (react-native-webview)

• Use the sharedCookiesEnabled and thirdPartyCookiesEnabled props to enable full cookie support.
• Set javaScriptEnabled={true} and domStorageEnabled={true}.
• Configure your WebView props to intercept new-window navigation requests from the portal and route them to the appropriate destination — either a child WebView or the system browser.

Flutter (flutter_inappwebview) Flutter (flutter_inappwebview)

• Set javaScriptEnabled: true and domStorageEnabled: true in InAppWebViewSettings.
• Use a shared InAppWebViewCookieManager to persist cookies.
• Configure your InAppWebViewSettings to handle new-window requests from the portal and route them to the appropriate destination.

4. Link Routing and Navigation 4. Link Routing and Navigation

This is the most technically sensitive part of the integration. Every link interaction inside the WebView needs to be routed correctly. A single misconfigured URL handler can silently break attribution for every merchant.

4.1 Link Categories 4.1 Link Categories

All URLs encountered in the WebView fall into three categories:

Category 1: Portal Navigation (Keep in WebView) Category 1: Portal Navigation (Keep in WebView)

These are links within the Shopping Portal itself — browsing categories, searching merchants, viewing offer details. These should always load inside the current WebView. Your link-interception logic should treat any URL on the portal’s domain as internal navigation.

Category 2: Merchant Click-Throughs (Keep in WebView — Recommended) Category 2: Merchant Click-Throughs (Keep in WebView — Recommended)

When a user taps a merchant offer, the portal generates an affiliate redirect URL. This URL passes through one or more affiliate network domains before landing on the merchant’s site. Under the recommended in-WebView model, this entire redirect chain — and the resulting merchant site — stays inside the WebView.

Your WebView’s navigation delegate or URL-loading handler should allow these redirects to proceed without interruption. Specifically:

• Do not intercept or modify redirect URLs. Affiliate networks use redirect chains that include tracking parameters in the URL. Stripping, rewriting, or re-routing these URLs will break attribution.
• Do not trigger universal links or app-to-app handoffs. If a merchant has an iOS universal link or Android App Link registered (e.g., amazon.com links opening the Amazon app), your WebView should suppress this behavior for affiliate redirect chains. On iOS, set the WKNavigationDelegate to handle link activation and prevent the OS from intercepting the URL. On Android, ensure the WebView does not delegate navigation to the system intent handler. For React Native and Flutter, use your WebView’s appropriate callbacks to intercept link activations.
• Do not open affiliate redirects in the system browser. This defeats the purpose of the in-WebView model and reintroduces all the attribution risks described in Section 2.

Category 3: External Links (Open Outside WebView) Category 3: External Links (Open Outside WebView)

Some links should intentionally leave the WebView — for example, links to your app’s terms of service, privacy policy, or help center. The portal marks these with standard browser behavior (target="_blank" or window.open()), so your WebView will receive a new-window or navigation request for them.

How you handle these is up to you: you can route them to the system browser (SFSafariViewController / Chrome Custom Tabs) or open them in a child WebView. Coordinate with your Client Success Manager to define which URLs fall into this category so you can test the correct behavior. Do not silently suppress these requests — that will cause links to appear broken to the user.

4.2 Back-Navigation 4.2 Back-Navigation

When the user is browsing a merchant site inside the WebView (in-WebView model), the back button in your app’s navigation chrome should step backward through the WebView’s history stack, not immediately close the WebView. This lets users return from a merchant site to the portal without losing their session. Only when the WebView’s history is fully unwound should the back button exit the portal.

5. Authentication and Session Management 5. Authentication and Session Management

The portal needs to know which user is browsing so that cashback earnings can be attributed to the correct account. How authentication is handled depends on whether unauthenticated access to the portal is supported in an embedded context.

5.1 Authenticated-Only Access (Recommended) 5.1 Authenticated-Only Access (Recommended)

There are two supported models for passing a user's identity to the portal if only logged-in users can access the portal. Which model applies to your integration is determined during onboarding.

Via URL Parameter Via URL Parameter

This is the simpler path. Your app already has the user authenticated and passes their identity to the portal by appending a user identifier to the portal’s entry URL when launching the WebView:

The portal reads the identifier on load, establishes the session, and strips the parameter from the visible URL. The user sees the portal already logged in, and no login or logout UI is required inside the portal itself. This works from any portal URL, so you can link users directly to a specific page (a merchant, a category, the home screen) and authentication will be handled transparently. This approach requires no additional coordination beyond agreeing on the identifier format.

Via OAuth (Required for Three-Way Split Model) Via OAuth (Required for Three-Way Split Model)

For partners operating under a three-way revenue split model, authentication uses an OAuth handshake rather than URL parameter passing. Your app generates an OAuth authorization code server-side using its existing authenticated session, then opens the WebView directly at the portal's authentication URL with the code appended:

The portal exchanges the code for an access token, extracts the user identity from the resulting JWT, and establishes the session. The user is redirected to the portal already logged in. As with the URL parameter model, this is silent from the user's perspective. Remaining details for this model are coordinated separately during onboarding.

5.2 Unauthenticated Access with Native Login Handoff 5.2 Unauthenticated Access with Native Login Handoff

If unauthenticated users can browse the portal (but must log in to earn cashback), the login flow must be handled natively in your app. The portal cannot redirect to a standalone login page because authentication is the native app's responsibility, not the portal’s. Showing a web-based login flow inside the WebView is also undesirable — it creates a disjointed experience and may conflict with your app's existing auth infrastructure.

The intended flow is as follows:

1. The user taps a login or earn-cashback prompt inside the portal while unauthenticated.
2. The portal sends a message to the native app via the JavaScript bridge: requestLogin with a return URL parameter.
3. The native app receives the requestLogin message through the bridge and presents its native login flow.
4. On successful authentication, the native app re-opens the WebView at the return URL using the appropriate authenticated pattern from Section 5.1 (with the user's identifier or OAuth code appended to the return URL).
5. The portal extracts and persists the identifier, strips it from the visible URL, establishes the session, and the user lands on the page they originally tried to access.

This flow requires close coordination between your team and ours to define the bridge message format, the return URL handling, and how session continuity is maintained across the WebView open/close cycle. Please reach out to your Client Success Manager to begin this process.

6. App Entry Points and Navigation 6. App Entry Points and Navigation

Your team is responsible for designing and building the surfaces that lead users into the Shopping Portal. The portal should feel native to your app — the transition in and out should match your existing design system and navigation patterns.

Common entry points include:

• A dedicated tab or menu item in your app’s main navigation.
• A promotional card or module on the app’s home screen.
• A banner or interstitial tied to a specific campaign or seasonal promotion.
• A deep link from a push notification or email campaign.

Regardless of the entry point, the destination is the same: your app launches the WebView and loads the portal URL (with authentication parameters if applicable). Wildfire can provide entry-point artwork, copy, and design guidance if needed.

7. QA and Testing 7. QA and Testing

A QA/UAT environment will be provided to support your testing process. Before launch, your team should plan for structured testing across the following areas.

7.1 Affiliate Attribution Validation 7.1 Affiliate Attribution Validation

This is the highest-priority testing area. For each test:

1. Open the portal in the WebView, select a merchant, and click through to the merchant’s site.
2. Verify that the redirect chain completes without interruption (no unexpected browser handoffs, no stripped parameters).
3. Confirm that the affiliate tracking cookie is present in the WebView’s cookie store after the redirect.
4. Complete a test purchase on the merchant’s site and verify that the conversion event is recorded in Wildfire’s tracking dashboard.

Repeat this flow across a representative set of merchants. Attribution issues are often merchant-specific or network-specific, so testing a single merchant is insufficient.

7.2 Link Behavior 7.2 Link Behavior

• Verify that portal navigation links stay inside the WebView.
• Verify that merchant click-throughs stay inside the WebView (if using the recommended model) or open in the system browser (if using click-out).
• Verify that no links trigger unintended universal link or App Link behavior.
• Verify that back-navigation works correctly, stepping through WebView history before exiting the portal.
• Verify that external links (terms, privacy, help) open in the correct target (system browser or child WebView) based on your configuration.

7.3 Device and OS Coverage 7.3 Device and OS Coverage

Test across a representative range of devices and OS versions. At a minimum: current and previous major versions of iOS and Android, and at least one low-end device per platform to check rendering performance.

7.4 Session Persistence 7.4 Session Persistence

• Verify that authenticated sessions persist when the user backgrounds and foregrounds the app.
• Verify that sessions persist if the user navigates away from the portal screen and returns.
• Verify that clearing the app’s cache or force-stopping the app behaves as expected (session may be lost; user should be re-authenticated on next entry).

7.5 Third-Party Interference 7.5 Third-Party Interference

Test with common third-party tools that may interfere with WebView behavior:

• Password managers (1Password, LastPass, system autofill) — these can intercept form submissions or inject iframes.
• Ad blockers and content blockers — these may block affiliate redirect domains.
• VPNs and DNS-based filters — these can alter redirect chains.
• Default browser override apps — these may intercept URL handoffs.

7.6 Monitoring and Failure Visibility 7.6 Monitoring and Failure Visibility

Ensure you have logging or monitoring in place to detect broken attribution flows, abandoned sessions, or unintended browser handoffs. Attribution failures are silent from the user’s perspective, so instrumentation is the only way to catch them before they become support tickets.

8. Alternative: Browser Click-Out Model 8. Alternative: Browser Click-Out Model

In the Browser Click-Out model, the Shopping Portal remains embedded in your app's WebView — the same WebView setup described throughout this guide applies. The difference is what happens when a user taps a merchant offer: instead of the affiliate redirect chain and merchant site loading inside the WebView, the portal sends a message to your native app via the JavaScript bridge, your app opens the merchant URL in the system browser (Safari, Chrome, or equivalent), and the user’s shopping session continues outside of your app. The portal session remains active in the background.

This option is appropriate when:

• Speed to market is the primary concern and engineering resources for a WebView integration are limited.
• The partner does not have strong requirements around keeping the user inside the app.
• Merchant site compatibility is a concern — complex checkout flows (3D Secure, OAuth popups, payment iframes) behave more reliably in a full browser environment.

Tradeoffs to be aware of: Because merchant purchases happen in the system browser, this model is subject to all the attribution risks described in Section 2 — ITP, ETP, cookie restrictions, and potential interference from browser extensions and content blockers. It also means the user leaves your app context entirely to complete their purchase and must manually return to the portal afterward, making it harder to re-engage them after their shopping session.

If you would like to explore this option, contact your Client Success Manager to discuss the native bridge setup and other details related to this model.

For questions about this guide, contact your Client Success Manager or email partners@wildfire.com.

Updated 17 Jun 2026