Shopping Portal Mobile Embedded Experience: Technical Implementation Guide

shopping portal mobile embedded integration guide technical reference for partners embedding the shopping portal as a webview within a native mobile application 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 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 cashback earnings depend on an unbroken affiliate attribution chain when a user clicks a merchant link in the portal, the following happens the click is routed through one or more affiliate network redirect urls the affiliate network drops a tracking cookie in the user’s browser or webview 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 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 ⚠️ attribution risk broken attribution is invisible to the user they will complete their purchase, expect cashback, and never receive it this is the single most common source of user complaints and support escalations in cashback programs the post click model you choose directly affects how often this happens comparison in webview vs browser click out in webview (recommended) browser click out attribution reliability high cookie jar is consistent; redirect chain stays intact within the same webview context lower subject to itp (safari), etp (firefox), and evolving chrome cookie policies third party cookies may be blocked or expire redirect chain integrity full control no handoff means no interception by os level link handlers, password managers, or default browser settings redirect chain exits your app universal links, smart link handlers, and browser extensions can intercept or alter the chain merchant site compatibility most merchant sites work some complex checkout flows (3d secure, oauth popups, new window requests) may require additional webview configuration full browser rendering all merchant sites work as expected, including complex payment and authentication flows user experience seamless user stays inside your app back navigation, session state, and app session are preserved throughout context switch user leaves your app to complete the purchase returning to the app requires the user to manually switch back implementation effort higher requires webview configuration, link routing logic, and thorough qa of merchant site rendering lower requires native bridge setup, but less qa burden than in webview since merchant sites render in the system browser recommended for partners prioritizing attribution accuracy and a cohesive user experience partners with limited engineering resources or where speed to market outweighs attribution risk 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 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 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 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) 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) 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) 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 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 all urls encountered in the webview fall into three categories 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) 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) 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 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 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) 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 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 {shopping portal url}?id={user identifier} 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) 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 {shopping portal url}/login?code={authorization code} 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 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 the user taps a login or earn cashback prompt inside the portal while unauthenticated the portal sends a message to the native app via the javascript bridge requestlogin with a return url parameter the native app receives the requestlogin message through the bridge and presents its native login flow 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) 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 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 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 this is the highest priority testing area for each test open the portal in the webview, select a merchant, and click through to the merchant’s site verify that the redirect chain completes without interruption (no unexpected browser handoffs, no stripped parameters) confirm that the affiliate tracking cookie is present in the webview’s cookie store after the redirect 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 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 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 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 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 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 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 of 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