sf-retail-media-library v1.4.1

\ \

SF Retail Media Library

\ \ \ \

User Guide

\ \ \ \ \ \

Last Updated: 23/10/2024

Version : 1

Owner: Belfiore Giovanni

\ \

1. What is the purpose 2

2. Example of adv 2

3. Considerations on technologies 2

5. thoughtful technologies 3

6. Implementation scheme 4

7. Installation 5

8. AdvManager 5

8.1 AdvManagerProps 6

8.2 Params defineSlot 7

9. Component Adv (React) 8

10. Example of use 9

\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \

1. What is the purpose

We want to create a library to be distributed via the NPM registry that manages the rendering of ADV retailers on the various shopfully applications. This library will take care of logic like:

• check user privacy consent

• render of adv in various sizes

• any ad refresh logics

2. Example of adv

3. Considerations on technologies

• Considering the widespread use of React.js among the marketplaces, the predominant technology for the development of this library will be React.

• Considering that this library will have to be inserted in other contexts that work with style sheets, it will be very important to consider the modules for the style sheets so that there is no overwriting of the classes present in the application project.

• Since the rendering of the ads is subject to the user's consent given and since this could come from various sources (oneTrust, Iubenda,...) the library will not take care of reading the cookies set by the consent managers but only of reading a state ( ACCEPTED / NOT ACCEPTED) provided by the marketplace of use

5. thoughtful technologies

• Vitejs: is a frontend build tool that helps you build web applications faster and more efficiently than traditional build tools like Webpack.

Vitejs' strengths are:

• Speed ​​of development

• Optimized builds

• Native support for ES Modules

• Simple setup

• Compatibility with modern frameworks

• TypeScript and JSX support

• React: we will take care of rendering the components and their state manager using React.js. At the moment it seems the most sensible choice given its widespread use in the company

• TypeScript: introduces static typing, which means you can declare the type of variables, functions, and objects. This helps prevent type-related runtime errors, such as when trying to access a property of an object that doesn't exist.

6. Implementation scheme

the library will essentially be composed of 2 components (without considering type or style files):

1. AdvManager: will take care of inserting the necessary script into the head of the application for adv requests to Google Tag Manager. furthermore, this component will contain the logic regarding the given consent released by the user

2. Adv: it will be the component that takes care of the actual rendering of the container component in google tag manager and will ignite the frame with the adv. this component will also take care of the dimensions to be given to the slot and any styles passed from the outside

\ \ \ \

7. Installation 

npm i sf-retail-media-library

8. AdvManager

AdvManager takes care of inserting the gpt.js script into the head and defining the slot rendering rules

\

8.1 AdvManagerProps

\

{
advConf:{
sizeMap: [728,90],
divId: ‘’div-gpt-ad-1713536623572,
path: ‘/234290497/next-retail-media-multisize’,
refreshTime: 100,
},
privacySettings: {...},
enableLazyLoadConfig:{
fetchMarginPercent: 123,
mobileScaling: 456, 
renderMarginPercent: 789
},
enableSingleRequest: true
}

\

8.2 Params defineSlot

• retailerId?: string;

• storeId?: string;

• platform?: string;

• placement?: string;

• trafficSourceType?: string;

• environment?: string;

• host?: string; | | | —- additionalTargetingParams | additional targeting in the format Record\<string,string> | |

9. Component Adv (React)

the Adv component takes care of rendering and defining the slot for the adv

          <Adv
               advConf={{
                 //divId: `div-gpt-ad-1713536623572`,
                 //path: `/234290497/next-retail-media-multisize`,
    		    specializationDivId: `section-1`,
                 specializationPath: `section/1`,
                 sizeMap: [728, 90],
                 refreshTime: 20,
               }}
               defaultTargetingParams={{
                 flyerId: '1174245',
                 retailerId: '656',
               }}
             />

Below is information on the component props:

• advConf: slot information

  • divId: overrides the value set in AdvManager.

  • path: overrides the value set in AdvManager.

  • specializationDivId: specializes the value set in AdvManager/Adv. the format for any specializations must be

\-\-....-\.

For example

section-1

• specializationPath: specializes the value set in AdvManager. the format for any specializations must be

\/\/..../\

For example

section/1

• sizeMap: overrides the value set in AdvManager.

• refreshTime: overrides the value set in AdvManager.

• defaultTargetingParams: default targeting list. Each value is optional

  • flyerId?: string;

  • retailerId?: string;

  • storeId?: string;

  • platform?: string;

  • placement?: string;

  • trafficSourceType?: string;

  • environment?: string;

  • host?: string;

• additionalTargetingParams: additional targeting in the format Record\<string,string>

10. Example of use 

import { Adv, AdvManager, IDefaultTargetingParams } from 'sf-retail-media-library'

function App() {
 AdvManager.init({
   advConf: { 
divId: 'div-gpt-ad-1713536623572', 
path: '/234290497/next-retail-media-multisize', 
sizeMap: [728, 90], 
refreshTime: 20
},
 });
 
return (
   <div>
     {Array.from({ length: 100 }, (_, i) => i).map((iii, i) => {
       return (
         <>
           <p>Lorem ipsum dolor sit amet.</p>
          
           <div style={{ display: 'flex', width: '100%', justifyContent: 'center' }}>
             <Adv
               key={i}
               advConf={{
                 //divId: `div-gpt-ad-1713536623572`,
                 //path: `/234290497/next-retail-media-multisize`,
         	   specializationDivId: `section-${i + 1}`,
                 specializationPath: `section-${i + 1}`,
                 sizeMap: i % 2 == 0 ? [300, 250] : [728, 90],
                 refreshTime: 20,
               }}
               defaultTargetingParams={{
                 flyerId: '1174245',
                 retailerId: '656',
               }}
             />
           </div>
         </>
       );
     })}
   </div>
 );
}