@schibsted/niche-advertory-adapter - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

lib/AdvertoryAdapter.d.ts

 import type { SiteConfig } from '@sch-inventory/advertory/types/core/interface/config';
-import type { AdsConfig, Device, LoadAdsParams, PartialAdvertoryConfig, invCodeBuilderSignature } from './types';
+import type { AdsConfig, Device, GlimrConfig, LoadAdsParams, PartialAdvertoryConfig, invCodeBuilderSignature } from './types';
 export declare class AdvertoryAdapter {
@@ -7,2 +7,3 @@ private _advertoryConfig;
     private _glimr;
+    set glimr(newGlimrConfig: Pick<GlimrConfig, 'enabled'>);
     private _initAdvertoryPackage;
@@ -23,3 +24,2 @@ private _initialized;
     });
-    clearPlacements(): void;
     initialize(initializationConfig: {
@@ -32,4 +32,4 @@ glimr: {
     loadAds(options: LoadAdsParams): void;
-    reLoadAds(): void;
+    private _reLoadAds;
     set device(device: Device);
 }

lib/AdvertoryAdapter.js

 export class AdvertoryAdapter {
+    set glimr(newGlimrConfig) {
+        this._glimr.enabled = newGlimrConfig.enabled;
+    }
     constructor({ advertoryConfig, glimr, initAdvertoryPackage, nicheAdsConfig, nicheInvCodeBuilder, }) {
@@ -17,3 +20,2 @@ this._device = null;
     }
-    clearPlacements() { } // TODO figure out if it's needed or doable
     initialize(initializationConfig) {
@@ -23,6 +25,7 @@ this._glimr.enabled = initializationConfig.glimr.enabled;
         this._initialized = true;
-        this.reLoadAds();
+        this._reLoadAds();
     }
     loadAds(options) {
         var _a, _b, _c, _d, _e, _f;
+        // TODO clear other placements that are already loaded or check if trigering load re-loads existing ads, not needed for MinMote but will most likely be needed for Tek and Pent (horseshoe)
         this._lastLoadAdsParams = options;
@@ -52,3 +55,3 @@ if (!this._initialized || !this._device) {
     }
-    reLoadAds() {
+    _reLoadAds() {
         if (this._lastLoadAdsParams) {
@@ -60,4 +63,4 @@ this.loadAds(this._lastLoadAdsParams);
         this._device = device;
-        this.reLoadAds();
+        this._reLoadAds();
     }
 }

package.json

 {
     "name": "@schibsted/niche-advertory-adapter",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "Package bridging inventory's advertory package with niche next.js apps",
@@ -26,3 +26,3 @@ "main": "lib/index.js",
     },
-    "gitHead": "0961b00cd637c37c079beb52e086b98aa705f16a"
+    "gitHead": "f80bff720067a97c1e4dcedb305ab2d4ba8d1005"
 }

README.md

 # `niche-advertory-adapter`
 
-> TODO: description
+Library that bridges the gap between `@sch-inventory/advertory` and Niche projects working on Next.js. `@sch-inventory/advertory` is published only on Artifactory.
+
+[Link to Advertory](https://github.schibsted.io/inventory/advertory)
+
+By design this library is not directly using `@sch-inventory/advertory` so that for most cases you will have do to changes in at most 2 projects from:
+
+-   `@schibsted/niche-advertory-adapter`
+-   `@sch-inventory/advertory`
+-   web frontent you are working on
+
+API of this library is largely compatible with `@schibsted/niche-ads` library to simplify the switch.
+
+## Usage
+
+### Creating instance
+
+```js
+import { initAdvertoryPackage } from '@sch-inventory/advertory/core/minmote';
+import { Device } from '@schibsted/niche-advertory-adapter';
+import type { invCodeBuilderSignature } from '@schibsted/niche-advertory-adapter';
+import { AdvertoryAdapter } from '@schibsted/niche-advertory-adapter';
+import { adsConfig } from '@constants/ads';
+
+const mapDevice = (device: Device) => {
+    switch (device) {
+        case Device.Desktop:
+            return 'wde';
+        case Device.Mobile:
+            return 'wph';
+        case Device.Tablet:
+            return 'wtb';
+        default:
+            throw new Error('Unknown device');
+    }
+};
+
+const nicheInvCodeBuilder: invCodeBuilderSignature = (placement, device, pageType) =>
+    `no-minmote-${mapDevice(device)}-${pageType}_${
+        Array.isArray(placement.adFormat) ? placement.adFormat[0] : placement.adFormat
+    }`;
+
+export const ads = new AdvertoryAdapter({
+    advertoryConfig: {
+        country: 'no',
+        defaultThreshold: 200,
+        fullscreenScroll: {
+            ...
+        },
+        prebid: {
+            ...
+        },
+        publisher: 'minmote',
+        tcf: {
+            enabled: false,
+        },
+    },
+    glimr: {
+        clientId: 'H3IYO2A4LD43YPFZIJLN',
+    },
+    initAdvertoryPackage,
+    nicheAdsConfig: adsConfig,
+    nicheInvCodeBuilder,
+});
+```
+
+#### Configuration
+
+-   `advertoryConfig` - configuration passed to advertory's `initAdvertoryPackage` function, check [advertory documentation](https://github.schibsted.io/inventory/advertory) for more details
+-   `glimr` - configuration for glimr, only required parameter is `clientId` (it's disabled by default, at this point of initialization we don't know if we can use glimr due to user consents)
+-   `initAdvertoryPackage` - function that initializes advertory package, it's different for each project (different import from advertory package)
+-   `nicheAdsConfig` -
+    -   `keywords` - keyboards to be set on the whole ad call
+    -   `pageOptions` - passed to advertory, look [there](https://github.schibsted.io/inventory/advertory#pageoptions) for documentation
+    -   `placements` - placement configuration, not advertory format, our is much shorter
+-   `nicheInvCodeBuilder` - function building invCode based on placement config, device and pageType, example implementation is provided above
+
+`nicheAdsConfig` example:
+
+```js
+{
+    keywords: {
+        common: {
+            'no-sno-publishergroup': 'schibsted',
+        },
+        desktop: {
+            article: {
+                'aa-sch-page_type': 'article',
+            },
+            common: {
+                'aa-sch-supply_type': 'web_desktop',
+            },
+            front: {
+                'aa-sch-page_type': 'front',
+            },
+            other: {
+                'aa-sch-page_type': 'other',
+            },
+        },
+        mobile: {
+            article: {
+                'aa-sch-page_type': 'article',
+            },
+            common: {
+                'aa-sch-supply_type': 'web_phone',
+            },
+            front: {
+                'aa-sch-page_type': 'front',
+            },
+            other: {
+                'aa-sch-page_type': 'other',
+            },
+        },
+        tablet: {
+            article: {
+                'aa-sch-page_type': 'article',
+            },
+            common: {
+                'aa-sch-supply_type': 'web_tablet',
+            },
+            front: {
+                'aa-sch-page_type': 'front',
+            },
+            other: {
+                'aa-sch-page_type': 'other',
+            },
+        },
+    }
+    pageOptions: {
+        member: 9700, // 9700 - regular member, 9826 - test seat
+        disablePsa: true,
+        enableSafeFrame: true,
+    },
+    placements: {
+        common: {
+            allowedFormats: ['banner', 'video', 'native'],
+            native: {
+                desc2: { required: false },
+                icon: { required: false, sizes: [{}] },
+                image: { required: false, sizes: [{}] },
+                sponsoredBy: { required: false },
+                title: { required: false },
+                video: { min_duration: 0, required: false },
+            },
+            noBidIfUnsold: true,
+        },
+        desktop: {
+            article: [
+                {
+                    adFormat: 'netboard_1',
+                    sizes: [...netboardSizes, nativeSize],
+                    targetId: 'text_ad_1',
+                },
+            ],
+            front: [
+                {
+                    adFormat: ['brandboard_1', 'fullscreen'],
+                    sizes: [...brandboardSizes, takeoverSize],
+                    targetId: 'front_ad_1',
+                },
+            ],
+         },
+        mobile: {
+            article: [
+                {
+                    adFormat: 'board_1',
+                    sizes: [...boardSizes, nativeSize],
+                    targetId: 'text_ad_1',
+                },
+            ],
+            front: [
+                {
+                    adFormat: ['board_1', 'board_fullscreen'],
+                    sizes: [...boardSizes, takeoverSize, nativeSize],
+                    targetId: 'front_ad_1',
+                },
+            ],
+        },
+        get tablet() { //usually the same as desktop
+            return adsConfig.placements.desktop;
+        },
+    }
+```
+
+### Initalization
+
+Before you initialize ads you need to know if you can use glimr and have pulse instance.
+
+Initialize adapter:
+
+```js
+function adsInitialization(pulseInstance) {
+    return ads.initialize({
+        glimr: {
+            enabled: findGlimrPermissions(),
+        },
+        pulseInstance,
+    });
+}
+```
+
+If glimr consent changes at any point you can update it like this:
+
+```js
+ads.glimr = {
+    enabled: findGlimrPermissions(),
+};
+```
+
+If device changes you can update it like this:
+
+```js
+ads.device = device;
+```
+
+### Loading ads
+
+You are ready to load ads. On any page that you want ads to show you can call `loadAds` like this:
+
+```js
+ads.loadAds({
+    keywords: {
+        'aa-sch-context_keyword': adsKeywords,
+        'no-sno-news-sponsors': adTags,
+    },
+    pageType: 'article',
+});
+```
+
+`pageType` is required but you can skip `keywords` if you don't want to pass any additional keywords.
+
+## Warning
+
+-   at the moment there is no way to clear already loaded ads, this functionality was not needed for MinMote but likely will be introduced with Tek and Pent
+-   **you must use `_` character as a delimiter in target ids** (e.g. `front-ad-1` must be changed to `front_ad_1`) this is currently a limitation of `@sch-inventory/advertory`

src/AdvertoryAdapter.ts

@@ -21,2 +21,6 @@ import type { Placements, SiteConfig } from '@sch-inventory/advertory/types/core/interface/config';
 
+    set glimr(newGlimrConfig: Pick<GlimrConfig, 'enabled'>) {
+        this._glimr.enabled = newGlimrConfig.enabled;
+    }
+
     private _initAdvertoryPackage: (config: SiteConfig) => Promise<void>;
@@ -54,4 +58,2 @@
 
-    clearPlacements() {} // TODO figure out if it's needed or doable
-
     initialize(initializationConfig: {
@@ -66,6 +68,7 @@ glimr: {
         this._initialized = true;
-        this.reLoadAds();
+        this._reLoadAds();
     }
 
     loadAds(options: LoadAdsParams) {
+        // TODO clear other placements that are already loaded or check if trigering load re-loads existing ads, not needed for MinMote but will most likely be needed for Tek and Pent (horseshoe)
         this._lastLoadAdsParams = options;
@@ -120,3 +123,3 @@ if (!this._initialized || !this._device) {
 
-    reLoadAds() {
+    private _reLoadAds() {
         if (this._lastLoadAdsParams) {
@@ -129,4 +132,4 @@ this.loadAds(this._lastLoadAdsParams);
         this._device = device;
-        this.reLoadAds();
+        this._reLoadAds();
     }
 }

No alert changes

Improved metrics

Total package byte prevSize

21527

increased by56%

Lines of code

351

increased by1.74%

Number of lines in readme file

237

increased by5825%

No dependency changes