--- title: AdSpirit Integration slug: experience/adspirit-integration docTags: createdAt: 2025-02-12T13:09:10.052Z --- 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: 1. **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)) 2. **List of ads** and there corresponding placements for desktop and mobile in design 3. **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". 4. 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**. :::BlockQuote \{ "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. ![](https://api.archbee.com/api/optimize/ygR6KtT9QI_R0u3uKTJsm/5weYcTZTQgHDI17jXUYBB_image.png) :::BlockQuote \{ "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: :::BlockQuote // 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](https://adsprit-example.glitch.me/)** 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. :::BlockQuote \
\ \
\
\ \ \Anzeige\ \
\
\
::: ### 4. When adding to your page. Add item in proper place: ![](https://api.archbee.com/api/optimize/ygR6KtT9QI_R0u3uKTJsm/xUBJ_BTSZmm4n1Ln4EuU8_image.png "select Ad item") ![](https://api.archbee.com/api/optimize/ygR6KtT9QI_R0u3uKTJsm/TQq-jhP4MaxZsact6P0bP_image.png) We should use conditional loading of mobile/tablet or desktop ads (check if project handles proper screen types like $context.device\_type): :::BlockQuote \[ \{ "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 :::BlockQuote @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