Storefront Hooks Documentation

overview storefront hooks provide a communication interface between the purple experience (angular application) and custom javascript code ( custom js ) this system allows external code to extend and customize the storefront's behavior without modifying the core application setup hooks are defined in the custom js file and registered on the global window\ storefronthooks object the hooks are triggered at specific points during the application lifecycle // example setup in custom js window\ storefronthooks = { onpurpleserviceinit () => { console log('purple service initialized'); }, // other hooks }; available hooks service lifecycle hooks onpurpleserviceinit() triggered when the purpleservice is fully initialized and ready to serve requests use case initialize external services, set up initial configurations parameters none return void window\ storefronthooks onpurpleserviceinit = () => { // initialize tracking services, ads, or other external integrations }; navigation hooks onnavigationend(params) triggered after angular's navigationend event use case track page views, update analytics parameters event angular navigationend event object router angular router instance viewcontext context data object return void window\ storefronthooks onnavigationend = (params) => { console log('navigated to ', params event url); // track page views }; onnavigationstable(params) triggered when the app becomes stable after angular navigation (including initial load) use case refresh ads after route changes, perform post navigation actions parameters all parameters from onnavigationend previousurl previous url (optional) currenturl current url return void window\ storefronthooks onnavigationstable = (params) => { // ideal for refreshing ads after route changes if (params previousurl !== params currenturl) { // refresh advertisements } }; content hooks oncontentloaded(params) triggered after angular content is fully loaded use case content specific tracking, modify content display parameters content catalogcontent object post catalogpost object (for bundle content) context context data object return void window\ storefronthooks oncontentloaded = (params) => { console log('content loaded ', params content name); // track content views, modify content presentation }; purchase hooks beforecontentpurchase(purchaseinfo) triggered before a content purchase is performed use case validate purchases, show custom purchase flows, intercept purchases parameters purchaseinfo actionconfig purchase action configuration return hookbeforepurchaseresult (continue | cancel | error) window\ storefronthooks beforecontentpurchase = async (purchaseinfo) => { // custom validation or purchase flow if (customvalidation()) { return { type 'continue' }; } else { return { type 'cancel' }; } }; beforesubscriptionpurchase(purchaseinfo) triggered before a subscription purchase is performed use case custom subscription flows, validation parameters purchaseinfo actionconfig subscription action configuration return hookbeforepurchaseresult (continue | cancel | error) window\ storefronthooks beforesubscriptionpurchase = async (purchaseinfo) => { // custom subscription logic return { type 'continue' }; }; user state hooks entitlementchanged(params) triggered when user entitlement changes (login/logout/subscription changes) use case update user specific ui, sync external services parameters newstate current entitlementuserdata oldstate previous entitlementuserdata (optional) return void window\ storefronthooks entitlementchanged = (params) => { console log('user entitlement changed ', params newstate); // update external user profiles, analytics }; subscriptionschanged(params) triggered when user subscriptions change use case track subscription changes, update ui parameters subscriptions array of appsubscription objects return void window\ storefronthooks subscriptionschanged = (params) => { console log('subscriptions updated ', params subscriptions length); // update subscription dependent features }; advertisement hooks onadinit() triggered to initialize pre bid scripts for ads use case set up ad networks, initialize bidding parameters none return void window\ storefronthooks onadinit = () => { // initialize ad networks, prebid scripts }; beforerenderad(params) triggered before an ad is rendered use case custom ad rendering logic, ad blocking parameters id ad slot identifier slot ad slot object config ad configuration refresh whether this is a refresh (optional) return boolean (true = continue with default rendering, false = skip) window\ storefronthooks beforerenderad = (params) => { console log('rendering ad ', params id); // return false to prevent default ad rendering return true; }; isadrefreshpaused() triggered to check if ad refresh should be paused use case pause ads during video playback, user interactions parameters none return boolean (true = pause refresh, false = allow refresh) window\ storefronthooks isadrefreshpaused = () => { // check if ads should be paused return isvideoplaying(); }; isaddisabled(id) triggered to check if specific ads should be disabled use case disable ads on certain devices or screen sizes parameters id ad identifier return boolean (true = disable ad, false = show ad) window\ storefronthooks isaddisabled = (id) => { // disable ads on mobile devices return window\ innerwidth < 768; }; ui hooks getintersectionmargin() triggered to get intersection margin for lazy loading use case control when components load based on viewport proximity parameters none return string (css margin value, e g , "500px") window\ storefronthooks getintersectionmargin = () => { // load components 500px before they become visible return "500px"; }; purchase result types when implementing purchase hooks, return one of these result types { type 'continue' } proceed with the platform's purchase { type 'cancel' } silently cancel the purchase process { type 'error', code? error code } cancel with error (code unused for subscriptions) best practices error handling wrap hook implementations in try catch blocks as the system will log errors but continue execution async support purchase hooks support both synchronous and asynchronous implementations defensive coding always check if hooks exist before calling them ( window\ storefronthooks hookname? () ) performance keep hook implementations lightweight to avoid blocking the ui testing test hooks across different user states and navigation patterns example implementation // complete example in custom js window\ storefronthooks = { onpurpleserviceinit () => { console log('storefront initialized'); // initialize analytics, ads, etc }, onnavigationstable (params) => { // track page views gtag('config', 'ga measurement id', { page path params currenturl }); }, beforecontentpurchase async (purchaseinfo) => { // show custom purchase dialog const proceed = await showcustompurchasedialog(purchaseinfo); return proceed ? { type 'continue' } { type 'cancel' }; }, entitlementchanged (params) => { // update user session in external systems updateexternalusersession(params newstate); } };