AdSpirit Integration

12min
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)
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/﻿
!!! 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/)
In ads.adspirit.configuration add proper script id adspirit-header-script and url 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:
select Ad item
﻿
﻿
﻿
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
﻿
Deposit a font in the HTML Experience with Experience Builder
Static ads