ℹ️ Using the Advantage Wrapper is highly recommended as it makes implementing Advantage high-impact formats on your website quick and easy. But if you already have custom implementations of the formats that you want, you can choose not to use the wrapper.
diff --git a/www/docs/index.md b/www/docs/index.md
index 36486c9..59a4264 100644
--- a/www/docs/index.md
+++ b/www/docs/index.md
@@ -2,136 +2,140 @@
pageClass: docs
---
+
+
Docs > Get started
- ℹ️ Advantage is still in
-Welcome to the Advantage documentation! Advantage revolutionizes high-impact display advertising by providing a unified, secure, and standardized platform for both publishers and advertisers. Whether you're looking to implement high-impact formats on your website or create engaging advertisements, this documentation will guide you through every step.
-
-## Quick Start
-
-### For Publishers & Website Owners
-
-Ready to implement high-impact advertising formats on your site? Start with our comprehensive publisher guide.
-
-👉 **[Publisher Tutorial](./tutorial/publisher)** - Learn how to integrate Advantage on your website
-
-### For Creatives & Advertisers
-
-Want to create compelling Advantage-compatible advertisements? Our creative tutorial has you covered.
-
-👉 **[Creative Tutorial](./tutorial/creative)** - Build high-impact ads that work seamlessly across platforms
-
-## What You'll Learn
-
-### 🎯 **Core Concepts**
-
-Understand the fundamental building blocks of Advantage:
-
-- **[Formats](./concepts/formats.md)** - High-impact ad formats like Topscroll, Midscroll, and Welcome Page
-- **[Wrapper](./concepts/wrapper.md)** - The secure container that manages ad display
-- **[Messaging Protocol](./concepts/creative.md)** - How ads communicate with websites
-- **[UI Layer](./concepts/ui-layer.md)** - Customization and theming options
-- **[Integrations](./concepts/integration.md)** - How formats connect with your website
+Advantage is a unified, secure, and standardized platform for high-impact display advertising.
+**Choose the path that best fits your role to get started.**
+
+BETA. Big changes might happen in the near future
+ ℹ️ Advantage is still in BETA. Big changes might happen in the near future.
+
+
+
+
+
+
+
+
+
+ Publisher (AdOps)
++ The fastest way to get Advantage running on your site. No complex build tools required. +
+ + Quick Start Guide + +
+
+
+
+
+
+
+ Publisher (Dev)
++ Full control and customization. Integrate via NPM and leverage our comprehensive API. +
+ + Developer Guide + +
+
-### 🛠 **Available Formats**
-
-Explore the high-impact formats available in Advantage:
-
-- **[Topscroll](./formats/topscroll.md)** - Premium branding format that appears at the top
-- **[Midscroll](./formats/midscroll.md)** - Engaging mid-content format with parallax effects
-- **[Welcome Page](./formats/welcome_page.md)** - Full-screen welcome experience
-- **[Double Midscroll](./formats/double_midscroll.md)** - Extended midscroll format
-
-### 💡 **Developer Tools**
-
-Enhance your development workflow:
-
-- **[MCP Server](./ai-tools.md)** - AI-powered development assistance with live documentation access
-- **[Examples](./examples/hello-world.md)** - Ready-to-use code samples and implementations
-
-## Key Features
-
-
+
+
+ Creatives
++ Build ads that work everywhere. Learn how to use our messaging protocol for high-impact ads. +
+ + Creative Guide + +
-
-` component. This allows Advantage to take control when a high-impact ad is delivered.
```html
```
-You can control which ad formats are allowed for an `` by specifying them in the allowed-formats attribute. Provide a comma-separated list of format names; only these listed formats will be permitted for this specific wrapper instance.
-
-```html
-
-
-```
+### Step 3: Success!
-You can also dynamically set or update the allowed ad formats for an `` instance using its setAllowedFormats() JavaScript method. This method is useful for changing format permissions after the page has loaded or in response to user interactions.
+That's it! Your site is now ready to receive Advantage high-impact formats. When an Advantage-enabled creative is served into that slot, the wrapper will automatically handle the layout changes.
-Method: `element.setAllowedFormats(formatsArray)`
+---
-- `formatsArray`: An array of strings, where each string is a valid format identifier (e.g., `["MIDSCROLL", "WELCOME_PAGE"]`).
-- Ensure the format identifiers used are valid. See a list of built-in formats [here](/docs/concepts/formats)
+## Advanced Implementation (NPM) {#advanced-implementation-npm}
-```ts
-import { Advantage, IAdvantageWrapper } from "@get-advantage/advantage";
-const wrapper = document.querySelector(
- "advantage-wrapper"
-) as IAdvantageWrapper;
-wrapper.setAllowedFormats(["MIDSCROLL", "WELCOME_PAGE"]);
-```
+For developers who want full control, type safety, and custom integration logic.
-You can also choose to use a helper method that does the wrapping for you:
+### Step 1: Install Advantage
-```ts
-import { advantageWrapAdSlotElement } from "@get-advantage/advantage/utils";
+::: code-group
-/* advantageWrapAdSlotElement is a function that wraps an ad slot element with an
-Advantage-wrapper. It takes either a selector string or an HTMLElement as an argument.
-You can also pass an optional second argument to specify the formats to exclude for the wrapped ad slot.*/
-advantageWrapAdSlotElement("#ad-slot-to-be-wrapped", ["TOPSCROLL"]);
+```sh [npm]
+$ npm i @get-advantage/advantage
```
-The above code will take an ad slot like this...
-
-```html
-
+```sh [pnpm]
+$ pnpm add @get-advantage/advantage
```
-... and wrap it like this:
-
-```html
-
-
+```sh [yarn]
+$ yarn add @get-advantage/advantage
```
-Your ad slot is now Advantage enabled!
+```sh [bun]
+$ bun i @get-advantage/advantage
+```
-`. These formats are pre-configured with the necessary styling out-of-the-box. Integration with your site might still be necessary for optimal performance. You can customize the integration through settings passed to Advantage. Pass your custom integrations in the `formatIntegrations` array. When the `` is about to transform into a format, it will run the provided `setup` function, so that you can make the necessary adjustments.
+You can customize how Advantage interacts with your site's UI (e.g., hiding sticky headers) using the `configure` method.
```ts
+import { Advantage, AdvantageFormatName } from "@get-advantage/advantage";
+
const advantage = Advantage.getInstance();
advantage.configure({
formatIntegrations: [
{
format: AdvantageFormatName.TopScroll,
- /**
- * This function will be run before a transformation into a high-impact format, allowing you to make adjustments that might be necessary
- * */
- setup: (
- wrapper: IAdvantageWrapper,
- adIframe: HTMLIFrameElement
- ) => {
- return new Promise((resolve, reject) => {
- /* Setup your site to accomodate the topscroll format here.
- Perhaps you might need to hide a sticky header menu or similar. */
-
- // call resolve when done
+ setup: (wrapper, adIframe) => {
+ return new Promise((resolve) => {
+ // Custom logic: e.g., document.querySelector('header').style.display = 'none';
resolve();
});
}
@@ -164,58 +100,43 @@ advantage.configure({
});
```
-#### Remote or local configuration
+### Step 4: Programmatic Wrapping
-If you don't want to bundle your configuration it is possible to make Advantage fetch it from a remote URL. To do so, simply supply the configure function with a `configUrlResolver`:
+If you prefer not to use HTML tags directly, you can wrap elements via JavaScript:
-```ts [remote config]
-advantage.configure({
- // If you want to, you can load the configuration from a remote file.
- // To do so, configure Advantage with a configUrlResolver, like this:
- configUrlResolver: () => {
- /* You could use the hostname or any other logic to determine the config file, or simply return a static URL.
- This is just an example of how you could dynamically load a config file based on the current hostname */
- return `https://example.com/configs/${window.location.hostname}.js`;
- }
-});
+```ts
+import { advantageWrapAdSlotElement } from "@get-advantage/advantage/utils";
+
+// Wraps the element and prepares it for Advantage formats
+advantageWrapAdSlotElement("#ad-slot-to-be-wrapped", ["TOPSCROLL"]);
```
-The remote configuration file should be a javascript file that exports the configuration like so:
+---
-```ts
-export default { ...configuration };
-```
+## Common Configuration Options
-#### Custom formats
+### Allowed Formats
-It is possible to create your own custom ad formats. These should be included into your configuration:
+You can restrict which formats are allowed on a specific wrapper:
-```ts
-advantage.configure({
- formats: [
- {
- name: "MyCustomFormat",
- description: "A custom format",
- setup: (wrapper: IAdvantageWrapper, ad?: HTMLElement) => {
- return new Promise((resolve) => {
- // Style the wrapper and make other adjustments here
- resolve();
- });
- }
- }
- ]
-});
+```html
+
+
+
```
-### Success!
+### Manual Format Control
-Congratulations! Your website is now Advantage enabled!
+If you need to force a format for testing purposes:
-### Step 6: Without the wrapper {#without-wrapper}
+```ts
+const wrapper = document.querySelector("advantage-wrapper");
+await wrapper.forceFormat("topscroll");
+```
-If you don't need the Advantage Wrapper but still want your website to be able to accept Advantage ads, you can use the [`AdvantageAdSlotResponder`](/api/classes/advantage_messaging_publisher_side.AdvantageAdSlotResponder.html) class.
+## Without the wrapper {#without-wrapper}
-Create a new instance of the class for each ad slot/placement that you want Advantage-enabled:
+If you don't need the Advantage Wrapper but still want your website to be able to accept Advantage ads, you can use the [`AdvantageAdSlotResponder`](/api/classes/advantage_messaging_publisher_side.AdvantageAdSlotResponder.html) class.
```ts
import { AdvantageAdSlotResponder } from "@get-advantage/advantage";
@@ -224,12 +145,9 @@ new AdvantageAdSlotResponder({
adSlotElement: document.querySelector("#advantage-enabled-ad-slot")!,
formatRequestHandler: (format, elem) => {
return new Promise((resolve) => {
- // handle the format request here, e.g. by transforming the parent element into the requested format
- // resolve the promise if the format transformation was succesful or reject it if it failed
+ // Manually handle the transformation logic here
resolve();
});
}
});
```
-
-The `formatRequestHandler` will be called as soon as an Advantage ad is loaded into the ad slot and requests a format. It is now up to you to transform the ad slot into the requested format and then call `resolve()`.
diff --git a/www/index.md b/www/index.md
index e2d8bf0..1f4fe4f 100644
--- a/www/index.md
+++ b/www/index.md
@@ -270,7 +270,7 @@ layout: page
An open-source solution designed to simplify, streamline and standardize
high-impact display advertising on the web
-
-📐 Unified Standards
-Consistent implementation across all platforms and buying channels, simplifying the advertising ecosystem.
-
-
-🔒 Secure By Default
-Built-in security measures protect both publishers and users while maintaining ad effectiveness.
-
-
-
-🛠 Flexible Customization
-Adapt formats to match your brand and user experience while maintaining performance standards.
-
-
+## Explore More
+⚡️ Efficiency & Effectiveness
-Optimized performance ensures fast loading times and maximum user engagement.
-
+
+ 🎯 Core Concepts
+ Learn about Formats, Wrappers, and the Messaging Protocol. + + + 🛠 Available Formats
+ Specs for Topscroll, Midscroll, Welcome Page and more. + + + 💡 Developer Tools
+ MCP Server and ready-to-use code examples. + + + 🔧 API Reference
+ Complete TypeScript API documentation. +
-## Common Use Cases
-
-### Publishers
-
-- **News & Media Sites** - Implement non-intrusive high-impact formats that maintain reading flow
-- **E-commerce Platforms** - Showcase promotional content without disrupting the shopping experience
-- **Content Publishers** - Monetize content with engaging, brand-safe advertising formats
-
-### Advertisers & Agencies
-
-- **Brand Awareness Campaigns** - Create memorable experiences with Topscroll and Welcome Page formats
-- **Product Launches** - Use high-impact formats to generate buzz and drive engagement
-- **Programmatic Buying** - Standardized implementation across multiple publisher sites
-
-## Getting Help
-
-### 📚 Documentation Structure
-
-- **Tutorials** - Step-by-step guides for implementation
-- **Concepts** - In-depth explanations of core functionality
-- **Formats** - Detailed specifications for each ad format
-- **Examples** - Working code samples and implementations
-- **API Reference** - Complete technical documentation
-
-### 🤝 Community & Support
+## Community & Support
- **[GitHub Issues](https://github.com/get-advantage/advantage/issues)** - Report bugs and request features
- **[Slack Community](https://join.slack.com/t/get-advantage/shared_invite/zt-2gy6c4z4m-4~pIuwRfe8eqPM5H7iV9MQ)** - Connect with other developers and get help
- **[Contributing Guide](../about/contributions.md)** - Learn how to contribute to the project
-
-### 🔧 Development Resources
-
-- **[API Documentation](../api/)** - Complete TypeScript API reference
-- **[GitHub Repository](https://github.com/get-advantage/advantage)** - Source code and examples
-- **[Changelog](./changelog.md)** - Track updates and new features
-
-## Next Steps
-
-
-
-Ready to transform your advertising experience? Choose your path above and start building with Advantage today!
diff --git a/www/docs/tutorial/creative.md b/www/docs/tutorial/creative.md
index cbcefb9..612bd11 100644
--- a/www/docs/tutorial/creative.md
+++ b/www/docs/tutorial/creative.md
@@ -6,35 +6,63 @@ pageClass: docs
# Creative tutorial
-This part of the tutorial is aimed at creatives who makes high-impact ads.
+This part of the tutorial is aimed at creatives and developers who build high-impact ads.
-### Step 1: Install Advantage
+## Quick Start (CDN) {#quick-start-cdn}
-To install Advantage, run the following command in your terminal:
+The fastest way to build an Advantage-compatible ad is to use our CDN-hosted library. This works in any HTML environment.
-::: code-group
+### 1. Include the Library
-```sh [npm]
-$ npm i @get-advantage/advantage
-```
+Add this to your ad's HTML:
-```sh [pnpm]
-$ pnpm add @get-advantage/advantage
+```html
+
```
-```sh [yarn]
-$ yarn add @get-advantage/advantage
-```
+### 2. Request a Format
+
+Use the following script to communicate with the publisher's website and request a high-impact format (like `topscroll`).
+
+```html
+
```
-:::
+---
+
+## Professional Workflow (NPM)
+
+For advanced creative builds using modern bundling tools (Webpack, Vite, etc.).
-### Step 2: Import the messenger
+### 1. Install
-Import the `AdvantageCreativeMessenger` class into your creative's code.
+```sh
+npm i @get-advantage/advantage
+```
+
+### 2. Implementation
```ts
import {
@@ -42,137 +70,35 @@ import {
AdvantageMessageAction,
AdvantageFormatName
} from "@get-advantage/advantage/creative";
-```
-
-### Step 3: Start a session
-Create a new instance of the AdvantageCreativeMessenger class and start a session. When a session is established, send a message to request the format the the creative banner was built for:
+async function init() {
+ const messenger = new AdvantageCreativeMessenger();
+ const session = await messenger.startSession();
-```ts [TypeScript]
-async function main() {
- const advantageMessenger = new AdvantageCreativeMessenger();
- const session = await advantageMessenger.startSession();
if (session) {
- const response = await advantageMessenger.sendMessage({
+ const response = await messenger.sendMessage({
action: AdvantageMessageAction.REQUEST_FORMAT,
format: AdvantageFormatName.TopScroll
});
+
if (response?.action === AdvantageMessageAction.FORMAT_CONFIRMED) {
- // Yay! Format is confirmed by Advantage on the website
- // Start the ad here
- }
- if (response?.action === AdvantageMessageAction.FORMAT_REJECTED) {
- // Oh no, the format was rejected. Time to for a backup plan
+ // Initialize your high-impact creative logic here
}
- } else {
- // For some reason, a session was not created. Perhaps the site isn't yet Advantage enabled?
}
}
-main();
-```
-## Play CDN
-
-Use the CDN to try Advantage right in the browser without any build step.
-
-::: warning
-The CDN is designed for development purposes only, and is not intended for production.
-Talk to your tech vendor to load the script from a 3rd party certified CDN used for ad delivery.
-:::
-
-::: code-group
-
-```html{6,10-43} [JS]
-
-
-
-
-
-
-
-
- + Learn about Formats, Wrappers, and the Messaging Protocol. + + + 🛠 Available Formats
+ Specs for Topscroll, Midscroll, Welcome Page and more. + + + 💡 Developer Tools
+ MCP Server and ready-to-use code examples. + + + 🔧 API Reference
+ Complete TypeScript API documentation. +
Hello world!
- - - +init(); ``` -```html{10-14} [ESM] - - - - - - - -Hello world!
- - - -``` +--- + +## Why is this necessary? + +Standard ad banners are often stuck inside fixed-size `iframes`. To create "High Impact" experiences like parallax scrolling or full-screen takeovers, the ad needs a secure way to tell the parent website: *"I'm not a regular banner, please give me more space!"* + +Advantage provides this secure communication bridge. -::: +## Next Steps -::: tip -There are many more pre baked bundles available in the CDN. Check out the [CDN documentation](https://cdn.jsdelivr.net/npm/@get-advantage/advantage/dist/bundles/) for more information. -::: +- View the [Messaging Protocol](../concepts/creative.md) for more advanced actions. +- Check out the [Hello World Example](../examples/hello-world.md). diff --git a/www/docs/tutorial/publisher.md b/www/docs/tutorial/publisher.md index 1f45aaa..8090c0a 100644 --- a/www/docs/tutorial/publisher.md +++ b/www/docs/tutorial/publisher.md @@ -8,154 +8,90 @@ pageClass: docs This part of the tutorial is aimed at website owners and publishers who want to implement Advantage on their site(s). -### Step 1: Install Advantage - -To install Advantage, run the following command in your terminal: - -::: code-group - -```sh [npm] -$ npm i @get-advantage/advantage -``` - -```sh [pnpm] -$ pnpm add @get-advantage/advantage -``` +## Quick Start (CDN) {#quick-start-cdn} -```sh [yarn] -$ yarn add @get-advantage/advantage -``` - -```sh [bun] -$ bun i @get-advantage/advantage -``` - -::: +The easiest way to get started with Advantage is by using our CDN. This method is perfect for AdOps and sites where you want a low-code integration. -### Step 2: Import Advantage +### Step 1: Add the Advantage Script -Import Advantage and get a reference to it's singleton - -```ts [index.ts] -import { Advantage } from "@get-advantage/advantage"; +Add the following script tag to the `` of your website: -// Get a reference to the Advantage singleton -const advantage = Advantage.getInstance(); +```html + ``` -### Step 3: Decide if to use the Advantage Wrapper +### Step 2: Wrap your ad slots -Using the Advantage Wrapper is highly recommended as it makes implementing Advantage high-impact formats on your website quick and easy. But if you already have custom implementations of the formats that you want, you can choose not to use the wrapper. If so, you can jump ahead to [step 6](./publisher.html#without-wrapper). If you decide to use the Advantage wrapper, continue to the next step: - -### Step 4: Wrap your ad slots/placements - -It is now time to wrap your ad slots in the Advantage Wrapper. +Wrap your existing ad placements with the `
-
+
+
-
-
-
-
-
-
-
-
- ℹ️ Remember: It is the serving creative that advertise its intended format. In case you'r ad slot can serve both standard size ads and hight impact ads from the same ad slot. Nothing will happend if a none Advantage ad is served.
-
+:::
-#### Manual Format Control
+### Step 2: Import and Initialize
-If you need to programmatically control which format to display without waiting for communication from the ad iframe, you can use the wrapper's `forceFormat` method. This is useful for testing, custom business logic, or integration scenarios.
+Import Advantage and get a reference to its singleton.
-```ts
-// Get reference to the wrapper element
-const wrapper = document.querySelector("advantage-wrapper");
+```ts [index.ts]
+import { Advantage } from "@get-advantage/advantage";
-// Force a specific format
-await wrapper.forceFormat("interstitial");
+// Get a reference to the Advantage singleton
+const advantage = Advantage.getInstance();
```
-For detailed information about the `forceFormat` method, including all parameters and use cases, see the [Wrapper documentation](../concepts/wrapper.html#force-format).
-
-### Step 5: Configuration
+### Step 3: Configure Custom Integrations
-Advantage comes pre-built with a number of high-impact formats (detailed list and definitions coming soon) and they are included in the `high-impact display advertising on the web
-
+
Get started
