Server can control multiple publisher placements

adserver/api/serializers.py

@@ -60,6 +60,10 @@ class AdDecisionSerializer(serializers.Serializer):
     # This purposefully doesn't use a URLField so we can disregard invalid values rather than rejecting them
     url = serializers.CharField(max_length=256, required=False)
 
+    # The placement index (0-indexed)
+    # 1 or more means there's multiple placements on this page
+    index = serializers.IntegerField(required=False, min_value=0, max_value=9)
+
     # Used to pass the actual ad viewer's data for targeting purposes
     user_ip = serializers.IPAddressField(required=False)
     user_ua = serializers.CharField(required=False)

adserver/api/views.py

@@ -296,6 +296,7 @@ def decision(self, request, data):
                 keywords=keywords,
                 campaign_types=serializer.validated_data.get("campaign_types"),
                 url=url,
+                placement_index=serializer.validated_data.get("index"),
                 # Debugging parameters
                 ad_slug=serializer.validated_data.get("force_ad"),
                 campaign_slug=serializer.validated_data.get("force_campaign"),

adserver/decisionengine/backends.py

@@ -104,6 +104,10 @@ def __init__(self, request, placements, publisher, **kwargs):
             log.debug("Publisher has hit their daily cap. publisher=%s", self.publisher)
             self.campaign_types.remove(PAID_CAMPAIGN)
 
+        # The placement index (0-based) for this ad request
+        # 1+ means multiple ads on the same page
+        self.placement_index = kwargs.get("placement_index") or 0
+
         # When set, only return a specific ad or ads from a campaign
         self.ad_slug = kwargs.get("ad_slug")
         self.campaign_slug = kwargs.get("campaign_slug")
@@ -173,6 +177,14 @@ def get_placement(self, advertisement):
 
     def should_display_ads(self):
         """Whether to not display ads based on the user, request, or other settings."""
+        # Check if the publisher is allowed to have multiple placements
+        if not self.publisher.allow_multiple_placements and self.placement_index > 0:
+            log.info(
+                "Multiple placement request on publisher rejected. publisher=%s",
+                self.publisher,
+            )
+            return False
+
         return True
 
 

adserver/migrations/0087_publisher_allow_multiple_placements.py

@@ -0,0 +1,29 @@
+# Generated by Django 4.2.4 on 2023-09-21 22:20
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("adserver", "0086_region_topic_pricing"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="historicalpublisher",
+            name="allow_multiple_placements",
+            field=models.BooleanField(
+                default=False,
+                help_text="Can this publisher have multiple placements on the same pageview",
+            ),
+        ),
+        migrations.AddField(
+            model_name="publisher",
+            name="allow_multiple_placements",
+            field=models.BooleanField(
+                default=False,
+                help_text="Can this publisher have multiple placements on the same pageview",
+            ),
+        ),
+    ]

adserver/models.py

@@ -373,6 +373,11 @@ class Publisher(TimeStampedModel, IndestructibleModel):
         ),
     )
 
+    allow_multiple_placements = models.BooleanField(
+        default=False,
+        help_text=_("Can this publisher have multiple placements on the same pageview"),
+    )
+
     # Payout information
     skip_payouts = models.BooleanField(
         _("Skip payouts"),

adserver/tests/test_api.py

@@ -801,6 +801,26 @@ def test_sticky_decision(self):
         # Clear the cache so this setting doesn't mess up the next test
         cache.clear()
 
+    def test_multiple_placements(self):
+        self.query_params["index"] = 0
+        resp = self.client.get(self.url, self.query_params)
+        self.assertEqual(resp.status_code, 200)
+        self.assertTrue("id" in resp.json())  # Gets an ad successfully
+
+        # No ad since `publisher.allow_multiple_placements` is False (the default)
+        self.query_params["index"] = 1
+        resp = self.client.get(self.url, self.query_params)
+        self.assertEqual(resp.status_code, 200)
+        self.assertDictEqual(resp.json(), {})
+
+        self.publisher.allow_multiple_placements = True
+        self.publisher.save()
+
+        self.query_params["index"] = 1
+        resp = self.client.get(self.url, self.query_params)
+        self.assertEqual(resp.status_code, 200)
+        self.assertTrue("id" in resp.json())  # Gets an ad successfully
+
 
 class AdvertiserApiTests(BaseApiTest):
     def setUp(self):