--- title: Adserver API best practices slug: fluid-adserver-api/adserver-api-best-practices icon: 📢 docTags: createdAt: 2024-07-05T09:57:29.649Z --- ## Ad Server API Overview :::ExpandableHeading{isOpen="true"} ### Requirements The Pentaleap Adserver API is used to request and receive ads from the Pentaleap Retail Media platform.​ ​There are two variations of the API implementation based on your use case:​​ - **Standard Use Case**: Sourcing all campaigns directly from Pentaleap and API-synced demand sources (such as SKAI or Pacvue).​ - **3rd Party Demand Use Case**: Sourcing some or all demand from an existing third party or demand platform.​​ In both cases, the API implementation remains the same. However, the 3rd Party Demand use case requires the use of our [\[For 3rd Party Demand\] Implement Warmup for Demand Source calls](docId:6z7PZxWibKtgjWFyFrMWS).​​ ::: ## Implementation Types :::::ExpandableHeading{isOpen="true"} ### Backend vs Client Implementation Backend integration has the benefit of minimal, consistent network time between Client and Pentaleap adserver – app integration may add latency​ ::::Tabs :::Tab{title="Backend Integration"} ::Image[]{src="https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/Z7hDPTo9JaAXwH9ft0uhx_image.png" size="50" width="437" height="542" position="center" showCaption="false"} ::: :::Tab{title="Client Integration"} ::Image[]{src="https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/t_wUZZDXpkIjateUi2nwV_image.png" size="50" width="435" height="534" position="center" showCaption="false"} ::: :::: ::::: :::::ExpandableHeading{isOpen="true"} ### Component type suggested integration Recommended ways to integrate the different components​ ::::VerticalSplit{layout="middle"} :::VerticalSplitItem ### Backend requests **Ad Request:** Ensures low network latency with backends hosted in same regions. **Conversion Events:** In the backend to keep data hidden and prevent tampering ::: :::VerticalSplitItem ### Frontend Requests **Impressions:** In the browser which is aware if an ad on the screen or not. Data in tracking URLs are encrypted. **Clicks:** In the browser which is aware of click events. Data in tracking URLs are encrypted. ::: :::: ::::: ## Best Practices :::::ExpandableHeading{isOpen="true"} ### Ad Server API call ::::VerticalSplit{layout="right"} :::VerticalSplitItem **Accurate Metadata: **Ensure that all metadata (e.g., Ad Unit ID, UserID, search query, and category information) is accurate and complete to enable precise targeting and tracking. **Timely API Calls:** Make API calls as soon as the final list of products to be shown is known to ensure real-time ad delivery and relevance. **Verify Endpoints and DNS: **For each environment, Pentaleap will provide a set of endpoints, DNS, publisher, and site IDs. Verify that you are calling the correct endpoints for each environment to avoid misrouting and ensure data integrity.  ::: :::VerticalSplitItem ::: :::: ::::: :::::ExpandableHeading{isOpen="true"} ### Optimizing and testing connection speed ::::Tabs :::Tab{title="Re-use connections"} ::Image[]{src="https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/f8zdfK3fnRZvte9mg45Nd_image.png" size="50" width="574" height="574" position="center" showCaption="false"} ::: :::Tab{title="Don’t test speed locally"} ::Image[]{src="https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/53teOgcJFDSz9YTRSPyoR_image.png" size="50" width="550" height="574" position="center" showCaption="false"} ::: :::Tab{title="Load Tests"} ::Image[]{src="https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/LUXsh3EIfwoserZp_65FB_image.png" size="50" width="548" height="574" position="center" showCaption="false"} ::: :::: ::::: :::::::ExpandableHeading{isOpen="true"} ### Organic Products, Cross-Page Boosting and Third Party Demand ::::::Tabs :::Tab{title="Products per Request"} ### Most integrations send 40-100 products This gives us more relevant ads and better ad performance ![](https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/6pqKtDkgS2-1X4XlOZIaA_image.png) ::: :::::Tab{title="Cross Page Boosting"} ### Ideal integration solves for cross-page boosting and better overlap Batches of products can be split out in the backend or front-end in various ways ::::VerticalSplit{layout="right"} :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/AQe_eT4KDEIQn5Sx0xnX8_image.png) ::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/UT-enkukytXcIVChpLV6z_image.png) ::: :::: ::::: :::::Tab{title="Sourcing Demand"} ### Sourcing (third party) demand in parallel to search requests reduces latency Implementing timeouts on ad requests guarantees that impact on speed is minimal ::::VerticalSplit{layout="right"} :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/OWHkbXztwDF0gEY2nILTk_image.png) ::: :::VerticalSplitItem ![](https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/dKsaJ4sr47z5pLQL1g05L_image.png) ::: :::: ::::: :::::: ### Demand Sources & Ad Request Logic ::::Tabs :::Tab{title="Product Overlap"} **Desired behavior.** When relying solely on third-party sources for ad demand, it's beneficial to ensure that there's significant **overlap** between the products featured organically and those with bids from the demand source. This practice enhances the **relevance** of the displayed ads for the end user, leading to better **click-through rates** (CTR) for the brands and retailers involved. ![](https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/Sy4IXuY_uV4Rbs9Fgz7y5_image.png) ::: :::Tab{title="Duplicating sponsored products"} **Undesired behavior.** It's advisable to **refrain from inserting demand source** products into organic listings to achieve overlap. Doing so can create an **artificial scenario** that may result in the forced promotion of irrelevant products, undermining the user experience. ![](https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/KgRPGWKN5r38CTefKJv1m_image.png) ::: :::Tab{title="Removing duplicates"} **Undesired behavior.** **Removing duplicates** is also discouraged since it reduces the chance of achieving any overlap between organic and sponsored products. This limitation can decrease the opportunity for products to be sponsored, while simultaneously **increasing the likelihood of promoting irrelevant items.** ![](https://api.archbee.com/api/optimize/FKG7INSMP0SHaHefhjVDj/on-BJT1-wdhAmrJ2W4quB_image.png) ::: :::: :::::::