AdSpirit Integration

adspirit is a trusted ad platform for premium publishers this guide will cover the key setup steps, configuration options, and best practices to ensure a smooth and compliant integration preconditions before starting the integration, ensure you have the following resources ready adspirit script url proper script url (usually it is default for all https //cdn adspirit de/adasync min js https //cdn adspirit de/adasync min js ) list of ads and there corresponding placements for desktop and mobile in design consent management ensure the cmp (consent management platform) is configured with vendors relevant to adspirit (including iab compliant vendor ids) "cdn adspirit de", "apoverlag adspirit de" use pxp version 3 8 8 and higher important notes adspirit ads can be tested even at localhost without any additional queryparams or configuration we don't need to trigger any consent given event, while adspirit reads it on their side adspirit require adsrefresh some customers use subscribtion plans to disable ads list of available ads with their ids https //adsprit example glitch me/ https //adsprit example glitch me/ !!! if conditional loading of ads for proper screens needed we need to have conditional loading in view\ json relying on $context device type and not a css based condition with display block/none how to guide 1\ experience config go to experience builder create or edit experience config default/storefront/assets/experience config json as adspirit manages consent on their side we don't need to add additional consent configuration to purple ads consent (for other ad services, which is not audienzz you might need to add vendorid and iabvendorid you find vendorid in your consent manager configurations and find iabvendorid here https //iabeurope eu/vendor list tcf/ https //iabeurope eu/vendor list tcf/ ) in ads adspirit configuration add proper script id adspirit header script and url https //cdn adspirit de/adasync min js https //cdn adspirit de/adasync min js to refresh adspirit ads dynamically, we need access to the loaded adspirit script adspirit provides its api via asm async data , which is a standard global object after the script loads we must pass asm async data as the scriptwinkey to reference it correctly to hide ads for subscribed users , we need to check for a specific window key that indicates whether the user is a premium subscriber the window key varies by project in the latest project , this key is cmp pur loggedin if window\[cmp pur loggedin] is true, ads should not be shown { "language" "de", "purple" { "version" { "major" 1, "minor" 0 }, "ads" { "adspirit" { "configuration" { "headerscriptid" "adspirit header script", "headerscripturl" "https //cdn adspirit de/adasync min js", "scriptwinkey" "asm async data", "premiumsubwinkey" "cmp pur loggedin" } } } } } 2\ in default/storefront/assets , click on the 'ads json' file, or create one { "adslots" \[ { "id" "adspirit desktop superbanner 272", "providerconfig" { "id" "272", "type" "adspirit", "height" 110, "params" "$function customchecker($context adspiritparams)", "platform" "desktop", "spacetop" 2, "width" 1058, "spacebottom" 1 }, { "id" "adspirit mobile header 270", "providerconfig" { "id" "272", "type" "adspirit", "params" "$function customchecker($context adspiritparams)", "platform" "mobile tablet", "spacetop" 2, "spacebottom" 1 } } } ] } top level id can be anything specific to project params resides in content properties\["adspirit urlparameters"] coming from hub, should be set in builder as $context adspiritparams in url resolver json it can be set per article, and not per home page for example, so to properly handle this use some $function customchecker($context adspiritparams) to resolve to empty string if there is no $context adspiritparams defined example of setting of those adspiritparams in url resolver json // url resolver json const setadspiritparams = (content) => { let params = ""; if ( content && content properties && content properties && content properties\["adspirit urlparameters"] ) { params = content properties\["adspirit urlparameters"]; } return params; }; const handlearticle = async ({ match, dataresolver, resolveddata }) => { rest of the code const articleslug = getarticleslug(match); const postcontents = resolveddata\[articleslug] contents; if (!postcontents length) { return { notfound true }; } const content = await dataresolver findcontentbyid(postcontents\[0] id); rest of the code const adspiritparams = setadspiritparams(content); rest of the code return { viewname view names article default, viewcontext { content, rest of the code adspiritparams, rest of the code }, }; }; 3\ final created ad element structure note this section is just to see what will be our resulted add from above configurations (no configurations part here) with crossed items to be configurable 1\) mobile tablet platform (it could be "desktop", "mobile", "tablet", "large desktop" or combined "mobile tablet") if configured in scss file (check adspirit scss file mentioned below ) this classes should not be used for conditional showing of the ads with display block/none 2\) space top 1 space bottom 2 configurations are also added in scss file for proper styling (check adspirit scss file mentioned below ) 3) pid= 12345 id of the ad proper ads and their ids can be found here 4) param1=value1 could be something like "special=no ad" and should be configured through builder and placed in from content properties\["adspirit urlparameters"] to $context adspiriturlparams or something similar can be added with or without "&" at the beginning of the string, other params add should match "&" structure in between of each query param "special=no ad & param1=value1" 5\) styles width 300px & height auto width and height if not provided will be 100% and auto respectevely you should set them as number without px \<div class="ad mobile tablet "> \<! container element for the ad where platform config should be added like "mobile tablet" > \<div class="ad content space top 1 space bottom 2 "> \<div class="ad content inner"> \<ins class="asm async creative" style="width 300px ; height auto ; text align left; text decoration none;" data asm cdn="cdn adspirit de" data asm host="apoverlag adspirit de" data asm params="pid= 12345\&param1=value1 "> \</ins> \<span class="ad badge">anzeige\</span> \</div> \</div> \</div> 4\ when adding to your page add item in proper place we should use conditional loading of mobile/tablet or desktop ads (check if project handles proper screen types like $context device type) \[ { "adid" "adspirit desktop superbanner 272", "type" "ad", "condition" { "and" \[ { "value" "$context device type", "operation" "equals not", "comparevalue" "phone" }, { "value" "$context device type", "operation" "equals not", "comparevalue" "tablet" } ] } }, { "adid" "adspirit mobile header 270", "type" "ad", "condition" { "or" \[ { "value" "$context device type", "operation" "equals", "comparevalue" "phone" }, { "value" "$context device type", "operation" "equals", "comparevalue" "tablet" } ] } } ] 5\ you can also have styles configurations you can apply your ad specific styles like this /src/default/storefront/assets/scss/adspirit scss @use " /common ui" as ; @use " /media query" as ; ad { \ ad badge height 15px; \ ad badge padding left 4px; \ ad badge padding right 4px; \ ad badge font size 10px; \ ad badge font style normal; \ ad badge font weight 400; \ ad badge line height 13px; \ ad badge dark color white; \ ad badge dark background #68626280; \ ad badge light background #ffffff80; \ ad badge light color #686262; \ ad content inner margin left auto; \ ad content inner margin right auto; \ space 1 15px; \ space 2 30px; @include media xlarge { \ ad badge font size 12px; \ ad badge line height 15px; } } ad { display block; position relative; } lg\\\ hidden { @include media large { display none; } } ad badge { height var( ad badge height); padding left var( ad badge padding left); padding right var( ad badge padding right); font size var( ad badge font size); font style var( ad badge font style); font weight var( ad badge font weight); line height var( ad badge line height); position absolute; top 0; right 0; z index 123; background var( ad badge dark background); color var( ad badge dark color); text align right; } ad content { overflow x hidden; display flex; justify content start; } ad content inner { margin left var( ad content inner margin left); margin right var( ad content inner margin right); position relative; } asm async creative { position relative; } ad content space top 1 { margin top var( space 1); } ad content space top 2 { margin top var( space 2); } ad content space bottom 1 { margin bottom var( space 1); } ad content space bottom 2 { margin bottom var( space 2); } ad ressort previews { max width calc(100% var( side bar width)); } ad end of article { padding left var( outer gutters); } 6\ configure ads placement in your project according to mockups 7\ notes native ads are currently not covered in pxp code swiper ads are not covered in pxp code