goopubtag
Version:
React library for Google Publisher tag
407 lines (396 loc) • 14.7 kB
text/typescript
import { ReactNode } from 'react';
/** GPT types
* - reference: https://developers.google.com/publisher-tag/reference
* - Definitely typed: https://www.npmjs.com/package/@types/google-publisher-tag
*/
/**
* A generic type for dynamic props with children
*/
type ChildrenWithProps<T> = T & {
/**
* The children prop passed to a react component
*/
children: ReactNode;
};
/**
* Key-value pairs used for targeting
*/
type Attributes = Record<string, string | string[]>;
/**
* A basic Ad size, defining the width and height respectively
*/
type Size = readonly [number, number];
/**
* Sizes can either be:
* - A string value to define behaviour, eg "fluid"
* - A basic Ad size (width X height)
* - An array of basic Ad sizes (width X height) corresponding to the viewport
*/
type Sizes = string | Size | (string | Size)[];
/**
* A combination of viewport definitions and ad sizes for responsive ads
*/
type SizeMapping = {
/**
* A viewport size, defining the width and height respectively
*/
viewport: Size;
/**
* The ad sizes that can be served for the viewport size provided
*/
sizes: Sizes;
};
/**
* Allows configuration of all privacy settings from a single API using a config object
*/
type PrivacySettings = {
/**
* Enables serving to run in limited ads mode to aid in publisher regulatory compliance needs. When enabled, the GPT library itself may optionally be requested from a cookie-less, limited ads URL.
*/
limitedAds: boolean;
/**
* Enables serving to run in non-personalized ads mode to aid in publisher regulatory compliance needs.
*/
nonPersonalizedAds: boolean;
/**
* Indicates whether the page should be treated as child-directed.
*/
childDirectedTreatment: boolean;
/**
* Enables serving to run in restricted processing mode to aid in publisher regulatory compliance needs.
*/
restrictDataProcessing: boolean;
/**
* Indicates whether to mark ad requests as coming from users under the age of consent.
*/
underAgeOfConsent: boolean;
};
type CollapseSlot = Collapse | "expand_strict";
type Collapse = "default" | "expand" | "collapse";
type OutOfPageExtra = Pick<SlotUnit, "adUnit" | "targetingArguments" | "onSlotLoad" | "onSlotRequested" | "onSlotIsViewable" | "onSlotRenderEnded"> & {
/**
* If a combination of out of page ads and static ads are used, this should be `true`.
*/
withStaticAds?: boolean;
};
type AnchorOutOfPage = {
type: "anchor";
settings: AnchorSettings;
};
type AnchorSettings = {
position: "top" | "bottom";
};
type RewardedOutOfPage = {
type: "rewarded";
settings: RewardedSettings;
};
type RewardedOnReadyEvent = {
makeRewardedVisible: () => void;
};
type RewardedOnGrantedEvent = {
payload: {
amount: string;
type: string;
};
};
type RewardedSettings = {
onReady?: (event: RewardedOnReadyEvent) => void;
onClosed?: (event: unknown) => void;
onGranted?: (event: RewardedOnGrantedEvent) => void;
};
type RailOutOfPage = {
type: "rail";
settings: RailSettings;
};
type RailSettings = {
position: "left" | "right";
};
type OutOfPageTypes = AnchorOutOfPage | RewardedOutOfPage | RailOutOfPage;
type OutOfPage = OutOfPageExtra & OutOfPageTypes;
type Mapping = {
addSize: (viewport: Size, sizes: Sizes) => Mapping;
build: () => Mapping;
};
/**
* Enables lazy loading in GPT as defined by the config object. For more detailed examples, see the {@link https://developers.google.com/publisher-tag/samples/lazy-loading Lazy loading sample}.
*/
type LazyLoad = {
/**
* Fetch slots within 5 viewports.
*/
fetchMarginPercent: number;
/**
* Render slots within 2 viewports.
*/
renderMarginPercent: number;
/**
* Double the above values on mobile.
*/
mobileScaling: number;
};
type SlotRender = Slot & {
getSlotElementId: () => string;
};
type SlotVisibilityChanged = Slot & {
getSlotElementId: () => string;
};
type Event<T> = {
serviceName: string;
slot: T;
};
type SlotLoadEvent = Event<SlotRender>;
type SlotRequestEvent = Event<SlotRender>;
type SlotRenderEndedEvent = Event<SlotRender>;
type SlotViewableEvent = Event<SlotVisibilityChanged>;
/**
* Defines shared props across both the GPTProvider and GPTSlot
* Generally the GPTSlot prop will overwrite what's defined in the GPTProvider
*/
type GPT<PageAttributes extends Attributes = Attributes> = {
/**
* The parent ad unit code. The Ad unit path follows the format:
*
* ```network-code/[parent-ad-unit-code/.../]ad-unit-code```, where:
*
* - **parent-ad-unit-code** are the codes of all parent ad units (only applies to non-top level ad units). This is the adUnit.
*/
adUnit?: string;
/**
* The size mappings for responsive ads
*/
sizeMapping?: SizeMapping[];
/**
* Initial Ad Sense attributes
*/
adSenseAttributes?: Attributes;
/**
* Initial targeting attributes
*/
targetingArguments?: PageAttributes;
};
/**
* The parameters available to the Slot Provider component
*/
type SlotProvider<PageAttributes extends Attributes = Attributes> = GPT<PageAttributes> & {
/**
* The network id or code is a unique identifier for the Ad Manager network the ad unit belongs to
*/
networkId: number;
/**
* If personalized Ads is set. For more information on personalized ads, see {@link https://support.google.com/admanager/answer/9005435 here}.
*/
personalizedAds?: boolean;
/**
* Enables single request mode for fetching multiple ads at the same time. This requires all Publisher Ads slots to be defined and added to the PubAdsService prior to enabling the service. Single request mode must be set before the service is enabled.
*/
singleRequest?: boolean;
/**
* Returns whether or not initial requests for ads was successfully disabled by a previous PubAdsService.disableInitialLoad call. Returns true if a previous call to PubAdsService.disableInitialLoad was successful, false otherwise.
*/
disableInitialLoad?: boolean;
/**
* Enables serving to run in limited ads mode to aid in publisher regulatory compliance needs.
*/
limitedAds?: boolean;
/**
* @ignore
* Enables lazy loading in GPT as defined by the config object.
*/
lazyLoad?: boolean | LazyLoad;
/**
* Defines the fallback behaviour for when an ad fails to load. The 3 options are:
*
* `default`: The default behaviour, can be used to unset previous values
*
* `expand`: In this configuration, ad slots are collapsed by default and only expand if they can be filled. Use this if slots will not be filled most of the time
*
* `collapse`: In this configuration, ad slots are expanded by default and collapse only if they cannot be filled. Use this if slots will be filled most of the time
*/
fallback?: Collapse;
outOfPage?: OutOfPage;
};
type SlotUnit<A extends UnitTargeting = UnitTargeting> = GPT<A["attributes"]> & {
/**
* The network id or code is a unique identifier for the Ad Manager network the ad unit belongs to
*/
networkId?: string;
/**
* The slot id. The Ad unit path follows the format:
*
* ```network-code/[parent-ad-unit-code/.../]ad-unit-code```, where:
*
* - **ad-unit-code** is the code for the ad unit to be displayed. This is the slotId
*/
slotId: A["slotId"];
/**
* The ad sizes that can be served for the viewport size provided
*/
sizes: Sizes;
/**
* **This is different behaviour to the `fallback` prop in the GPTProvider**
* Defines the fallback behaviour for when an ad fails to load. The 3 options are:
*
* `default`: The default behaviour, can be used to unset previous values
*
* `expand`: In this configuration, ad slots are collapsed by default and only expand if they can be filled. Use this if slots will not be filled most of the time
*
* `collapse`: In this configuration, ad slots are expanded by default and collapse only if they cannot be filled. Use this if slots will be filled most of the time
*
* `expand_strict`: In this configuration, the ad unit will:
* - not be collapsed initially
* - not be collapsed even if an ad does not load
*/
fallback?: CollapseSlot;
/**
* A callback for when the slot is successfully loaded
* @param event The slot load event
* @returns
*/
onSlotLoad?: (event: SlotLoadEvent) => void;
/**
* A callback for when the slot is successfully requested
* @param event The slot requested event
* @returns
*/
onSlotRequested?: (event: SlotRequestEvent) => void;
/**
* A callback for when the slot is viewable on the page
* @param event The slot is viewable event
* @returns
*/
onSlotIsViewable?: (event: SlotViewableEvent) => void;
/**
* A callback for when the slot rendering has ended
* @param event The slow render ended event
* @returns
*/
onSlotRenderEnded?: (event: SlotRenderEndedEvent) => void;
};
type Slot = {
collapseEmptyDivs(a?: boolean): void;
addEventListener(...args: unknown[]): void;
clearTargeting(k?: string): void;
setPrivacySettings(s: Partial<PrivacySettings>): void;
refresh: (...args: unknown[]) => unknown;
setTargeting(k: string, v: string | Array<string>): void;
addService(...args: unknown[]): unknown;
defineSizeMapping(mapping: Mapping): void;
setCollapseEmptyDiv(a?: boolean, b?: boolean): void;
};
type KeyTypes<T> = {
[K in keyof T]-?: K extends string ? string : K extends number ? number : K extends symbol ? symbol : never;
}[keyof T];
type KeyOfType<T, KeyType extends string | number | symbol = KeyTypes<T>> = Extract<keyof T, KeyType>;
type UnitTargeting<T extends Attributes = Attributes> = {
slotId: string;
attributes: T;
};
type SharedContextProps<PageAttributes extends Attributes = Attributes> = SlotProvider<PageAttributes> & {
debug?: boolean;
};
type GPTProviderProps<PageAttributes extends Attributes = Attributes> = ChildrenWithProps<SharedContextProps<PageAttributes>>;
type GPTSlotProps<A extends UnitTargeting = UnitTargeting> = SlotUnit<A> & {
className?: string;
dataTestId?: string;
};
/**
* The `GPTProvider` is required to initialize GPT as well as for rendering `GPTSlots` in the DOM.
* `GPTSlot` must be nested within a `GPTProvider`.
* @param props Initial GPT Provider props
* @returns
*/
declare const GPTProvider: <PageAttributes extends Attributes>(props: GPTProviderProps<PageAttributes>) => JSX.Element;
/**
* This is the Ad unit Element to be set in the DOM
*
* @param {GPTSlotProps} props
* @returns {JSX.Element}
*/
declare const GPTSlot: <A extends UnitTargeting = UnitTargeting>(props: GPTSlotProps<A>) => JSX.Element;
declare const GUIDELINES: {
UNIT_SIZE: {
readonly BILLBOARD: readonly [970, 250];
readonly SKYSCRAPER_WIDE: readonly [300, 600];
readonly SKYSCRAPER: readonly [160, 600];
readonly SKYSCRAPER_SLIM: readonly [120, 600];
readonly LEADERBOARD_XL: readonly [970, 90];
readonly LEADERBOARD_LARGE: readonly [920, 90];
readonly LEADERBOARD: readonly [728, 90];
readonly MPU: readonly [320, 250];
readonly MPU_300: readonly [300, 250];
readonly MOBILE_LEADERBOARD_LARGE: readonly [468, 60];
readonly MOBILE_LEADERBOARD_MEDIUM: readonly [320, 100];
readonly MOBILE_LEADERBOARD: readonly [320, 50];
readonly LINE_TEXT_UNIT: readonly [280, 18];
readonly ONE_BY_ONE: readonly [1, 1];
readonly FLUID: "fluid";
};
SCREEN_SIZE: {
readonly DESKTOP_LARGEST: readonly [1220, 0];
readonly DESKTOP_PLUS: readonly [970, 0];
readonly DESKTOP: readonly [861, 0];
readonly TABLET_PLUS: readonly [728, 0];
readonly TABLET: readonly [600, 0];
readonly MOBILE_PLUS: readonly [468, 0];
readonly MOBILE: readonly [320, 0];
};
};
/**
* A hook that enables dynamic updates to page level and slot configuration
*/
type UseGPT<PageAttributes extends Attributes> = {
/**
* This function when called will either:
*
* - refresh all ad slots (no parameter)
* - refresh only the ad slots provided
*
* @param adSlots The list of ad slot(s)
* @returns
*/
refresh: (adSlots?: string[]) => void;
/**
* This function when called will set the targeting attributes provided for a given slot
* @param slotId The unit slot id
* @param attributes The attributes to be set
* @returns
*/
setTargetingAttributes: <A extends UnitTargeting>(slotId: A["slotId"], attributes: A["attributes"]) => void;
/**
* This function when called will set the targeting attributes at a page level
* @param attributes The attributes to be set
* @returns
*/
setPageTargetingAttributes: (attributes: PageAttributes) => void;
/**
* This function when called will either:
*
* - clear all attributes for a given slot (when no attributes are provided)
* - clear specific attributes based on the attribute keys provided
* @param slotId The unit slot id
* @param attributes The attributes to be cleared
* @returns
*/
clearTargetingAttributes: <A extends UnitTargeting>(slotId: A["slotId"], attributes?: KeyOfType<A["attributes"]>[]) => void;
/**
* This function when called will either:
*
* - clear all page level attributes (when no attributes are provided)
* - clear specific page level attributes based on attribute keys provided
* @param attributes The attributes to be cleared
* @returns
*/
clearPageTargetingAttributes: (attributes?: KeyOfType<PageAttributes>[]) => void;
/**
* This function when called will update the privacy settings with the values provided
* @param settings The privacy settings
* @returns
*/
setPrivacySettings: (settings: Partial<PrivacySettings>) => void;
};
/**
* A hook that enables dynamic updates to page level and slot configuration
* @returns
*/
declare const useGPT: <PageAttributes extends Attributes = Attributes>() => UseGPT<PageAttributes>;
export { GPTProvider, type GPTProviderProps, GPTSlot, type GPTSlotProps, GUIDELINES, type RewardedOnGrantedEvent, type RewardedOnReadyEvent, type Size, type Sizes, type SlotLoadEvent, type SlotRenderEndedEvent, type SlotRequestEvent, type SlotViewableEvent, useGPT };