Hello World Sample (#3326)

Co-authored-by: Bret Gorsline <[email protected]>
prebid · May 23, 2024 · 93bf651 · 93bf651
1 parent 83e12ea
commit 93bf651
Show file tree

Hide file tree

Showing 7 changed files with 306 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -105,3 +105,9 @@ We welcome everyone to contribute to this project by implementing a specificatio
 
 ### Bug Fix
 Bug reports may be submitted by [opening a new issue](https://github.com/prebid/prebid-server/issues/new/choose) and describing the error in detail with the steps to reproduce and example data. A member of the core development team will validate the bug and discuss next steps. You're encouraged to open an exploratory draft pull request to either demonstrate the bug by adding a test or offering a potential fix.
+The quickest way to start developing Prebid Server in a reproducible environment isolated from your host OS
+is by using Visual Studio Code with [Remote Container Setup](devcontainer.md).
+
+## Learning Materials
+
+To understand more about how Prebid Server in Go works and quickly spins up sample instances, refer to the `sample` folder which describes various structured and integrated examples. The examples are designed to run on any platform that supports `docker` container.
diff --git a/sample/001_banner/app.yaml b/sample/001_banner/app.yaml
@@ -0,0 +1,20 @@
+port: 8000 # main auction server port
+admin_port: 6060 # admin server listening port
+
+external_url: localhost # host url of all 2 servers above
+status_response: "ok" # default response string for /status endpoint
+
+gdpr:
+  default_value: "0" # disable gdpr, explicitly specifying a default value is a requirement in prebid server config
+
+# set up stored request storage using local file system
+stored_requests:
+  filesystem: 
+    enabled: true
+    directorypath: ./stored_requests/data/by_id
+
+# set up stored response storage using local file system
+stored_responses:
+  filesystem:
+    enabled: true
+    directorypath: ./stored_responses/data/by_id
diff --git a/sample/001_banner/pbjs.html b/sample/001_banner/pbjs.html
@@ -0,0 +1,121 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        div.adslot {
+            border-color: red;
+            border-style: solid;
+            width: 300px;
+            height: 600px;
+        }
+        p.description {
+            border-style: solid;
+        }
+    </style>
+    <script src="//cdn.jsdelivr.net/npm/prebid.js@latest/dist/not-for-prod/prebid.js"></script>
+    <script>
+
+        var sizes = [
+            [300, 250],
+            [300, 600]
+        ];
+
+        // use the cool "Prebid Less" feature https://docs.prebid.org/dev-docs/adunit-reference.html#stored-imp
+        var adUnits = [
+            {
+                code: 'test-div-1',
+                mediaTypes: {
+                    banner: {
+                        sizes: sizes
+                    }
+                },
+	        bids: [{
+	            module: "pbsBidAdapter",
+	            ortb2Imp: {
+		      ext: { prebid: { storedrequest: { id: 'test-imp-id' }}}
+                    }
+                }]
+            }
+        ]
+
+        function renderAllAdUnits() {
+            var winners = pbjs.getHighestCpmBids();
+            for (var i = 0; i < winners.length; i++) {
+                renderOne(winners[i]);
+            }
+        }
+
+        // create an iframe in the div and write the winning ad into it
+        function renderOne(winningBid) {
+            if (winningBid && winningBid.adId) {
+                var div = document.getElementById(winningBid.adUnitCode);
+                if (div) {
+                    const iframe = document.createElement('iframe');
+                    iframe.scrolling = 'no';
+                    iframe.frameBorder = '0';
+                    iframe.marginHeight = '0';
+                    iframe.marginHeight = '0';
+                    iframe.name = `prebid_ads_iframe_${winningBid.adUnitCode}`;
+                    iframe.title = '3rd party ad content';
+                    iframe.sandbox.add(
+                        'allow-forms',
+                        'allow-popups',
+                        'allow-popups-to-escape-sandbox',
+                        'allow-same-origin',
+                        'allow-scripts',
+                        'allow-top-navigation-by-user-activation'
+                    );
+                    iframe.setAttribute('aria-label', 'Advertisment');
+                    iframe.style.setProperty('border', '0');
+                    iframe.style.setProperty('margin', '0');
+                    iframe.style.setProperty('overflow', 'hidden');
+                    div.appendChild(iframe);
+                    const iframeDoc = iframe.contentWindow.document;
+                    pbjs.renderAd(iframeDoc, winningBid.adId);
+                }
+            }
+        }
+
+    </script>
+    <script>
+        var pbjs = pbjs || {};
+        pbjs.que = pbjs.que || [];
+
+        pbjs.que.push(function () {
+            pbjs.setConfig({
+                s2sConfig: [{
+                    accountId: '1',
+                    adapter: "prebidServer",
+                    enabled: true,
+                    endpoint: {
+                        noP1Consent: "http://localhost:8000/openrtb2/auction",
+                        p1Consent: 'http://localhost:8000/openrtb2/auction',
+                    },
+                    timeout: 1000,
+                    debug: true,
+                    allowUnknownBidderCodes: true
+                }],
+            })
+
+            pbjs.addAdUnits(adUnits);
+            pbjs.requestBids({
+                bidsBackHandler: renderAllAdUnits
+            })
+        });
+    </script>
+
+</head>
+
+<body>
+    <h1>001_banner</h1>
+    <p class="description">
+        This demo uses Prebid.js to interact with Prebid Server to fill the ad slot <strong>test-div-1</strong>
+        The auction request to Prebid Server uses a stored request, which in turn links to a stored response.</br>
+        Look for the <strong>/auction</strong> request in your browser's developer tool to inspect the request
+        and response.
+    </p>
+    <h2>&#8595I am ad unit test-div-1 &#8595</h2>
+        <div id="test-div-1">
+        </div>
+</body>
+</html>
diff --git a/sample/001_banner/stored_request.json b/sample/001_banner/stored_request.json
@@ -0,0 +1,28 @@
+{
+    "id": "test-imp-id",
+    "banner": {
+        "format": [
+            {
+                "w": 300,
+                "h": 250
+            },
+            {
+                "w": 300,
+                "h": 600
+            }
+        ]
+    },
+    "ext": {
+        "prebid": {
+            "bidder": {
+                "pubmatic": {
+                    "publisherId": "111111",
+                    "adSlot": "test"
+                }
+            },
+            "storedbidresponse": [
+               { "bidder": "pubmatic", "id": "test-bid-id" }
+            ]
+        }
+    }
+}
diff --git a/sample/001_banner/stored_response.json b/sample/001_banner/stored_response.json
@@ -0,0 +1,46 @@
+{
+    "id": "test-auction-id",
+    "seatbid": [
+        {
+            "bid": [
+                {
+                    "id": "test-bid-id",
+                    "impid": "test-div-1",
+                    "price": 1,
+                    "adm": "<img src =\"http://files.prebid.org/creatives/prebid300x250.png\" />",
+                    "adomain": [
+                        "www.addomain.com"
+                    ],
+                    "iurl": "http://localhost11",
+                    "crid": "creative111",
+                    "w": 300,
+                    "h": 250,
+                    "mtype": 1,
+                    "ext": {
+                        "bidtype": 0,
+                        "dspid": 6,
+                        "origbidcpm": 1,
+                        "origbidcur": "USD",
+                        "prebid": {
+                            "meta": {
+                                "adaptercode": "pubmatic"
+                            },
+                            "targeting": {
+                                "hb_bidder": "pubmatic",
+                                "hb_pb": "1.00",
+                                "hb_size": "300x250"
+                            },
+                            "type": "banner",
+                            "video": {
+                                "duration": 0,
+                                "primary_category": ""
+                            }
+                        }
+                    }
+                }
+            ],
+            "seat": "pubmatic"
+        }
+    ],
+    "cur": "USD"
+}
diff --git a/sample/README.md b/sample/README.md
@@ -0,0 +1,65 @@
+# Sample
+
+The Sample describes several demos of quickly spinning up different Prebid Server instances with various preset configurations. These samples are intended for audiences with little knowledge about Prebid Server and plan to play around with it locally and see how it works.
+
+# Installation
+
+In the Sample, we use `docker` and `docker-compose` to instantiate examples; with docker providing a unified setup and interface,  you can spin up a demo server instance locally with only one command without knowing all the complexities.
+The docker image used in `docker-compose.yml` is the `Dockerfile` residing in the root level of the repository. 
+
+## Option 1 - Standard Docker Engine
+Install `docker` and `docker-compose` via the [official docker page](https://docs.docker.com/compose/install/#scenario-one-install-docker-desktop). If you cannot use the official docker engine due to restrictions of its license, see the option below about using Podman instead of Docker. 
+
+## Option 2 - Podman
+From MacOS, you can use [podman](https://podman.io/) with these additional steps:
+
+```sh
+$ brew install podman docker-compose
+$ podman machine init
+$ podman machine set --rootful
+$ podman machine start
+```
+
+# Examples
+
+## Common File & Structures
+All required files for each example are stored in a folder that follows the name pattern <number>_<name>. The `<number>` suggests its order and `<name`>` describes its title.
+
+The following files will be present for every example and are exclusively catered to that example.
+1. `app.yaml` - the prebid server app config.
+2. `pbjs.html` - the HTML file with `Prebid JS` integration and communicates with the Prebid Server. It also provides a detailed explanation of the example.
+3. `*.json` - additional files required to support the example. e.g. stored request and stored response.
+
+## Common steps 
+
+```sh
+#1 - To get to the sample folder if you are on the root repository directory.
+$ cd sample 
+
+#2a - This command builds a new image, you should execute this command whenever the repository source code changes.
+$ docker-compose build
+
+#2b - Optionally you could run `docker-compose build --no-cache` if you want to build an completely new image without using cache but results in slower time to build it.
+$ docker-compose build --no-cache
+
+#3a - Spin up a corresponding sample in a container - see Steps for details 
+$ docker-compose up <number>_<name>
+
+#3b - Optionally you could use `--force-recreate` flag if you want to recreate the container every time you spin up the container.
+$ docker-compose up <number>_<name> --force-recreate
+```
+
+### Detailed Steps
+1. To prevent `app.yaml` from being overwritten by other config files. Ensure that `pbs.yaml` or `pbs.json` config file **MUST NOT** be present in the root directory of the repository.
+
+2. Bring up an instance by running `docker-compose up <number>_<name>` in the `sample` folder.
+
+3. Wait patiently until you see ` Admin server starting on: :6060` and `Main server starting on: :8000` in the command line output. This marks the Prebid Server instance finishing its initialization and is ready to serve the auction traffic.
+
+4. you can copy the URL `http://localhost:8000/status` and paste it into your browser. You should see `ok` in the response which is another way to tell the Prebid Server that the main auction server is up and running.
+
+5. Open a new tab in your browser and turn on the console UI. If you are using Chrome, you can right-click on the page and click `inspect`. Once the console UI is on, click on the `Network` tab to inspect the traffic later.
+
+6. Copy the URL `http://localhost:8000/static/pbjs.html?pbjs_debug=true` into your browser. It starts the example immediately with debugging information from `Prebid JS`, and you can inspect the request and response between `Prebid JS` and `Prebid Server`.
+
+7. After playing with the example, type `docker-compose down`. This is to shut down the existing Sample so you can start the next one you want to select.
diff --git a/sample/docker-compose.yml b/sample/docker-compose.yml
@@ -0,0 +1,20 @@
+version: "3.9"
+services:
+  001_banner:
+    platform: linux/amd64
+    build:
+      context: ../
+      dockerfile: Dockerfile
+      args:
+        - TEST=false
+    image: pbs-sample
+    container_name: 001_banner
+    privileged: true
+    ports:
+      - "8000:8000"
+      - "6060:6060"
+    volumes:
+      - ../sample/001_banner/app.yaml:/usr/local/bin/pbs.yaml
+      - ../sample/001_banner/pbjs.html:/usr/local/bin/static/pbjs.html
+      - ../sample/001_banner/stored_request.json:/usr/local/bin/stored_requests/data/by_id/stored_imps/test-imp-id.json
+      - ../sample/001_banner/stored_response.json:/usr/local/bin/stored_responses/data/by_id/stored_responses/test-bid-id.json