Alternative second ad placement for revshare partners

[davidfischer]

Adds a second possible ad placement for revenue share partners only. Still only a single placement will be selected, but this change offers a second possible placement in the footer with a larger placement. The server will decide which placement to choose based on inventory.

Branched from #695

[ericholscher]

This looks simple enough. Needs the merge from the prior change in the other PR.

We should also ensure the projects know this is coming before we ship it.

[davidfischer]

We should also ensure the projects know this is coming before we ship it.

I spoke with the pallets team directly. The other main revshare partner is Celery.

[ericholscher]

Should we follow up w/ Celery on the payout email thread perhaps?

[ericholscher]

I'm good to merge this as well if we want -- I don't think Celery cares too much.

[davidfischer]

I'll try to get the merge conflict fixed today, but I'd love a review from @humitos.

[humitos]

I tried this locally but I wasn't able to make it work. I'm not sure how to make the new ad placement to appear. How do I reproduce this behavior locally?

By the way, do you have an screenshot on how it looks on our theme and Alabaster themes?

[davidfischer]

I tried this locally but I wasn't able to make it work. I'm not sure how to make the new ad placement to appear. How do I reproduce this behavior locally?

Since the devserver requests a paid ad and there's no large format paid ads, it's not showing. I'll see if I can setup a better example.

Edit: I added a second placement in the public/index.html.

[humitos]

I see it in the development mode now.

How I can test it on the documentation to see how it looks there? I usually go to any local documentation that I have in the development instance and I see the ad there, but this never appears there. Is there any way I can force it to be displayed there?

[davidfischer]

How I can test it on the documentation to see how it looks there? I usually go to any local documentation that I have in the development instance and I see the ad there, but this never appears there. Is there any way I can force it to be displayed there?

If your local documentation has a matching placement (something like this), then it will be selected. There's a few things here:

• Currently there's no paid large format ad and a paid ad will always be chosen over an unpaid ad if possible. If you just have a single placement with data-ea-type="logo-large-v1", then it will be chosen.
• If you have two placements, both a large format and the regular one, then they need data-ea-priority.

[humitos]

I was able to test this locally and in production by adding a RAW HTML to my documentation. This is not the test I want to do here because we are missing testing the CSS selector and the real positioning on the page for different themes (ours, and Alabaster for now) --which is what I really want to test.

• https://github.com/readthedocs/test-builds/blob/large-ad-placement/docs/index.rst?plain=1#L8

We can merge and deploy this PR if we want and need it, but I'd like to have a way to test this placement without having to manually write HTML in my docs. Ideally, I'd like to change something easily in the ethicalads.js file locally to force the display of this large placement. That's all I need to be able to test this locally on multiple themes.

[davidfischer]

You can force an ad by putting data-ea-force-ad="large-format-house-ad-publisher-focused-20260114" (that's the ad slug) on the placement.

[humitos]

I put that attribute in the placement but it didn't work. How are you testing this to know that it works on Alabaster and our theme?

[davidfischer]

How are you testing this to know that it works on Alabaster and our theme?

I hadn't tested all the individual combinations separately. Is there a good way to do that?

[humitos]

He, that's the information that I've been trying to get from you to test this PR 😄: how to test this locally on development documentation?

We need a way on the JS code to force returning the new placement and the server responding with a real ad.

[humitos]

I pushed 4cbfb8b with the updates required from my point of view after doing some testing locally.

Let me know if those look correct to you.

This is the diff I've used to test it locally:

diff --git a/src/ethicalads.js b/src/ethicalads.js
index a7f0564..a8804db 100644
--- a/src/ethicalads.js
+++ b/src/ethicalads.js
@@ -84,7 +84,7 @@ export class EthicalAdsAddon extends AddonBase {
         selector = "nav.wy-nav-side > div.wy-side-scroll";
         element = document.querySelector(selector);
 
-        if (this.elementAboveTheFold(element)) {
+        if (!this.elementAboveTheFold(element)) {
           placement.setAttribute("data-ea-type", "readthedocs-sidebar");
           placement.classList.add("ethical-rtd");
           placement.classList.add("ethical-dark-theme");
@@ -136,7 +136,7 @@ export class EthicalAdsAddon extends AddonBase {
         selector = "div.sphinxsidebar > div.sphinxsidebarwrapper";
         element = document.querySelector(selector);
 
-        if (this.elementAboveTheFold(element)) {
+        if (!this.elementAboveTheFold(element)) {
           placement.classList.add("ethical-alabaster");
           placement.setAttribute("data-ea-type", "readthedocs-sidebar");
           knownPlacementFound = true;
@@ -332,7 +332,7 @@ export class EthicalAdsAddon extends AddonBase {
       }
 
       // For now, only show the larger ad format on revshare partners
-      if (data.publisher !== "readthedocs" && secondSelector !== null) {
+      if (data.publisher === "readthedocs" && secondSelector !== null) {
         const secondElementToAppend = document.querySelector(secondSelector);
         if (secondElementToAppend !== null) {
           if (secondSelector !== null) {

Alabaster

Read the Docs

[davidfischer]

Let me know if those look correct to you.

This looks right.

This is the diff I've used to test it locally:

My question was more how do you test addons against real docs sites normally?

[humitos]

This looks right.

Do you want me to resolve the conflicts and merge this PR?

My question was more how do you test addons against real docs sites normally?

I always test it on the Read the Docs development environment (inv docker.up inside readthedocs.org repository with export RTD_USE_PROMOS=True environment variable set), I don't test it on "real production documentations". However, if I'm in doubt about how they will look on a specific project, I try to build that project locally.

Also, I use https://readthedocs-addons.readthedocs.io/ that list a bunch of different themes/doctools to test so I don't have to keep that list in my memory. There is a switch that makes all the links to be local, pointing to test-builds.devthedocs.org/<theme or doctool>. If you have that version built locally, you can just click on all those links and quickly see how the ad looks on them.

Let me know if that helps. Otherwise, we can pair for a moment and try to set up this environment on your side.