advertisement-pkg
Contains Relevant Digital Header Bidding Wrapper for advertisements.
About
This library is created in an effort to integrate Relevant Digital HB Wrapper. It wraps Relevant HB JavaScript API that includes:
Related docs and access
- General Help Center
- API
- JavaScript API
- A/B Tests
- Relevant Ticket System Relevant Digital's workspace
Usage
npm install @smg-automotive/advertisement-pkg
AdProvider
The library needs a few configuration variables to work. For that reason, you should wrap your page/top level app component with the <AdProvider/>
context.
Configuring Alloy
To enable Alloy (optional), pass an alloyConfig
prop to the AdProvider
.
import { AdProvider } from '@smg-automotive/advertisement-pkg';
import type { AlloyConfig } from '@smg-automotive/advertisement-pkg';
const alloyConfig: AlloyConfig = {
alloyAppId: 'brand_ch_web', // {brand_name}_{web|ios|android|flutter} (e.g. autoscout24_ch_web)
cdnUrl: 'https://cdn.alloy.ch/client-sdk/2.x.x/alloy-sdk.umd.js',
env: 'prod', // or "stg"
dataLayer: {
context: {
logicalPath: 'detail', // logical path of web site section (e.g. "home", "search", "detail"...). Note: alloyAppId is automatically added as prefix, resulting in format: {alloyAppId}/{logicalPath}
contentId: '12345', // identifier of content currently shown on the page (e.g. listing ID). Note: Alloy team suggests only defining contentId for listing detail pages, for other pages set to empty string
},
user: {
// optional
sso: { id: 'user-123' }, // sso user identifier
externalIds: { foo: 'bar' }, // external user's identifiers
},
},
autostart: true, // optional, defaults to true. If false, window.alloySDK.start() is used for startup
consentCookieName: 'eupubconsent-v2', // optional, defaults to eupubconsent-v2. Alloy SDK internally checks consent cookie and do not send data to server if there is no required consent
preventProfiling: false, // optional, defaults to false. If set to true on mount, prevents Alloy script from being loaded
};
const App = () => (
<AdProvider
relevantDigitalConfigId="123abc"
astCdnUrl="https://acdn.adnxs.com/ast/ast.js"
relevantDigitalCdnUrl="https://relevant-cdn/123abc.js"
alloyConfig={alloyConfig}
shouldInjectScriptsOnPageLoad={true} // used to inject ad scripts on page load to boost the ad performance
>
<AdSlot />
</AdProvider>
);
AdSlot component
The AdSlot
component can be used to set two types of placements:
- Inactive placement(default): set on the page and invoked only when
useRelevantDigital
hook is called (invokes all inactive placements on the page). When this happens if you have mixed lazy and non-lazy loaded ads on page it will first initiate all non-lazy ones and in following request it will initiate the remaining lazy ones. On leaving the page hook will call destroySlots. Use whenever there is more than one inactive placement on page - this way you make one or possibly two (if some ads are lazy) calls to the relevant SDK to invoke all placements on a single page. - Standalone placement: invoked on component render, does not require
useRelevantDigital
to get invoked, but requires keywords to be set. Can still be used on same page with inactive ads, in that case there is no need to calldestroySlots()
as hook will clean them all. If is not used on page with the hook, then it should be set to calldestroySlots()
on its own by setting the paramdestroyOnUnmount
totrue
. Use when you absolutely must invoke ad on render. Example: In carousel, if ad is positioned later on the line, and you want to render it when the user swipes to it. Is also legit to be used if is only the single ad on the page and no more is planned to be added.
‼️⚠️ It is highly recommended to wrap the AdSlot
component in Error Boundary. This will prevent errors to bubble out and crash other elements that are above in the hierarchy, possibly even the whole page or site.
Inactive AdSlot placements example (invoked by the hook)
import { AdSlot, useRelevantDigital } from '@smg-automotive/advertisement-pkg';
const keywords = { page: ['home'], site: ['yoursite.ch'], foo: 'bar' };
const HomePage = () => {
useRelevantDigital({ keywords });
return (
<div>
<AdSlot adUnitId={1234567} id="home-top-banner" />
{/* ... page content */}
<AdSlot adUnitId={1234568} id="home-bottom-banner" />
</div>
);
};
export default HomePage;
Standalone AdSlot placement example (invoked on render)
import { AdSlot, useRelevantDigital } from '@smg-automotive/advertisement-pkg';
const keywords = { page: ['brand'], site: ['yoursite.ch'], foo: 'bar' };
const BrandPage = () => {
return (
<div>
<AdSlot
adUnitId={1234567}
id="brand-outside-right"
standalone
keywords={keywords}
destroyOnUnmount
/>
</div>
);
};
export default BrandPage;
Adjusting Native Add types
Native ads are configured by administrators and may change over time. To accommodate these changes and ensure type safety, you can adjust the types of native ads in your code using TypeScript generics.
type CustomType = {
customType: string;
};
const AdComponent: FunctionComponent<NativeAdComponentProps<CustomType>> = ({
id,
data,
}) => {
return <div>{data.customType}</div>;
};
return (
<div>
<AdSlot<CustomType> nativeAdComponent={AdComponent} />
</div>
);
Lazy loading
Is set per placement slot in Relevant Yield dashboard for detailed instructions check here Reloads and Lazy loads in HB Manager
Placement size depending on viewport size
Also covered in Relevant Yield dashboard.
Debugging
Set URL param:
?debugAdScripts=true
- activate debugging forreact-relevant
library together with prebid (pbjs
) and xanrd (apntag
)?ast_test=true
- we need to add when testing mobile web through simulation on a desktop device (else test with actual mobile device)?pbjs_debug=true
- debug only prebid?ast_test=true
- if we suddenly start gettingAdBadRequest
on testing environment, we probably got blocked by Xandr, in that case we should add this to URL?alydbg
- debug alloy
Analytics
Is injected automatically with relevant ad-stack. Chances are that is already set, but if not check Overview of setting up HB Analytics Can be customized per-site in Relevant Yield dashboard like: "Publisher accounts" > "SMG" (Edit button) > Tutti (or other site) "Programmatic tag" > expand "Custom Global JavaScript code". More in Adding Custom Dimensions
Development
npm run build
You can link your local npm package to integrate it with any local project:
cd advertisement-pkg
npm run build
cd <project directory>
npm link ../smg-automotive-example-pkg
Release a new version
New versions are released on the ci using semantic-release as soon as you merge into master. Please
make sure your merge commit message adheres to the corresponding conventions and your branch name does not contain forward slashes /
.