Guides

Setup your Ad Server (GAM)

Suggest Edits

Ad Server Setup

To set up your GAM Ad server, you will need to configure an Ad Unit that can be called with the following properties:

type AdRequestModel = {
  position_in_stories: string;  // The position of the ad in the list of stories (e.g., '1st', '2nd', etc.).
  total_ads_in_stories: string;  // The total number of ads that are expected to appear in the list of stories.
  widget_alias: string;  // A unique alias for the widget that will render the ad, useful for tracking and analytics.
  url: string;  // The URL associated with the story, to which the ad pertains.
  ad_id: string;  // A unique identifier for the requested ad.
} & CustomClientTargeting;

📘

CustomClientTargeting: These are optional client-specific properties that can be passed to the widget, which will be forwarded to the ad server.

Ad Response

Upon receiving the request, the ad server must execute a script that calls the function window.JoinStories.renderAd with a payload object in the following format:

type AdModel = {
  adId: string;  // The unique ID of the ad.
  adTitle?: string;  // Optional. The title of the ad.
  mediaType: "image" | "video";  // Specifies if the ad is an image or video.
  mediaUrl: string;  // The URL of the media file to be displayed.
  timeBeforeAdIsSkippable: number;  // The time (in seconds) after which the user is allowed to skip the ad.
  timeBeforeAdIsClosable: number;  // The time (in seconds) after which the user can close the ad. If greater than `timeBeforeAdIsSkippable`, it overrides the skip option.
  maxAdDuration: number;  // The maximum duration (in seconds) for which the ad will play. If the ad is a video, it will be truncated to this length if longer.
  additionalScript?: string;  // Optional. A script that can be executed after the ad is displayed.
  sequentialTargeting?: string;  // Optional. A value sent back to the ad server with the next request in the same story sequence, allowing for sequential ad targeting.
  ctaConfiguration?: {  // Configuration for the Call-to-Action (CTA) button displayed with the ad.
    href: string;  // The URL to navigate to when the CTA button is clicked.
    text: string;  // The text displayed on the CTA button.
    color?: string;  // Optional. The background color of the CTA button.
    textColor?: string;  // Optional. The color of the CTA button text.
    startIcon?: "ArrowBox" | "ArrowRight" | "ArrowUpRight" | "Cursor" | "Web" | "HandClicking";  // Optional. The icon to display on the CTA button.
    shape?: "pill" | "rounded" | "sharp";  // Optional. The shape of the CTA button (pill, rounded, or sharp edges).
  };
  
  // Trackers
  googleImpressionTracker?: string;  // Optional. A Google tracking URL that logs an impression when the ad is viewed.
  thirdPartyImpressionTrackers?: string[];  // Optional. A list of third-party tracking URLs to call when the ad is viewed.
  thirdPartyClickTrackers?: string[];  // Optional. A list of third-party tracking URLs to call when the ad is clicked.
};

Properties

KeyDescription
adIdThe unique identifier for the ad. This value should be received in the Ad Request.
adTitleOptional. The title of the ad. This can be used to display a heading above the ad.
mediaTypeThe type of media used in the ad, which can be either "image" or "video".
mediaUrlThe URL of the media file (image or video) that will be displayed in the ad.
timeBeforeAdIsSkippableThe number of seconds before the user is allowed to skip the ad.
timeBeforeAdIsClosableThe number of seconds before the user can close the ad. If this value is greater than timeBeforeAdIsSkippable, the ad cannot be skipped but only closed at this time.
maxAdDurationThe maximum duration (in seconds) for which the ad will be shown. For videos, it will cut off if the duration is exceeded. If an image is used, a default duration of 10 seconds is set if this value is not provided.
additionalScriptOptional. A JavaScript script that can be executed after the ad is rendered.
sequentialTargetingThis value can be returned with subsequent ad requests within the same story sequence, allowing for sequential ad targeting.
ctaConfigurationConfiguration settings for the Call-to-Action (CTA) button displayed with the ad. This configuration includes the URL to navigate to, button text, colors, and button shape.
googleImpressionTrackerOptional. A Google tracking URL to count ad impressions (when the ad is viewed by the user).
thirdPartyImpressionTrackersOptional. A list of third-party tracking URLs that are triggered when the ad is viewed by the user.
thirdPartyClickTrackersOptional. A list of third-party tracking URLs that are triggered when the user clicks on the ad.

Notes

  • Sequential targeting: By sending the sequentialTargeting property, the ad server can dynamically adjust which ad to show next based on user interaction with the current ad.
  • Time control: timeBeforeAdIsSkippable and timeBeforeAdIsClosable work together to control user interaction with the ad. Setting a higher value for timeBeforeAdIsClosable ensures the user must engage for a certain amount of time before they can exit the ad entirely.

Updated 2 days ago