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:

• xandr ad server
• Prebid ORG lib prebid.js
• Relevant Analytics

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.

import { AdProvider } from "@smg-automotive/advertisement-pkg";

const App = () => {
    return (
        <AdProvider
            relevantDigitalConfigId="123abc"
            astCdnUrl="https://acdn.adnxs.com/ast/ast.js"
            relevantDigitalCdnUrl="https://relevant-cdn/123abc.js"
        >
            <AdSlot />
        </AdProvider>
    )
}
export default App

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. 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
• 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 call destroySlots() as hook will clean them all. If is not used on page with the hook, then it should be set to call destroySlots() on its own by setting the param destroyOnUnmount to true.

Inactive AdSlot example

import { AdSlot, useRelevantDigital } from "@smg-automotive/advertisement-pkg";

const keywords = { page: ['home'], site: ['yoursite.ch'], foo: "bar" };

const BrandPage = () => {
    return (
        <div>
            <AdSlot
                adUnitId={1234567}
                id="brand-outside-right"
                standalone
                keywords={keywords}
                destroyOnUnmount
            />
        </div>
    );
}

export default BrandPage;

Inactive AdSlot example

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" />
		</div>
	);
}

export default HomePage;

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 for react-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 getting AdBadRequest on testing environment, we probably got blocked by Xandr, in that case we should add this to URL

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 /.