Shared ping post – PX Knowledge Base

Shared ping post allows publishers to view the list of bids per each leg available on the ping and select specific legs for selling the lead on the post.

How to enable shared ping post for a publisher

To start using shared ping post between PX and publisher, the following should be done:

Set Shared forwarding or Shared prediction type in publisher settings.
The publisher must insert leads including an additional distribution directives block in both ping and post requests.

Shared ping post includes several additional options:

The publisher can use one of two alternative ways of sending distribution directives on the ping.
PX can send responses to the publisher using leg names or hashed leg names.
There is also an option to configure the margin or fixed pricing per each leg.

Distribution directives

Distribution directives block in shared ping post contains the following data:

Num slots (mandatory) show how many times this lead can be sold;
Hashed leg name or Leg name (optional on ping, mandatory on post) indicates, to which legs publisher prefers to sell this lead. Only campaigns from indicated legs are considered as potential ones.

Publishers can either indicate specific legs on ping or not. See the examples below.

Code examples on ping

There are two alternative options on the ping:

1. Publishers can include only Num Slots parameter in the Distribution Directives block in ping request:

<DistributionDirectives>
   <NumSlots>5</NumSlots>
</DistributionDirectives>

In this case, in the ping response they will receive the list of all available legs that have eligible campaigns with their bids:

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Result Value="BaeOK">
        <TransactionID>A10151A2-0EB1-4536-9A6C-D3C87502E4B0</TransactionID>
        <Bid0>
            <Legname>Leg1</Legname>
            <Payout>8.50</Payout>
            <Status>Success</Status>
        </Bid0>
        <Bid1>
            <Legname>Leg2</Legname>
            <Payout>17.00</Payout>
            <Status>Success</Status>
        </Bid1>
        <Bid2>
            <Legname>Leg3</Legname>
            <Payout>11.90</Payout>
            <Status>Success</Status>
        </Bid2>
    </Result>
</Response>

2. Publishers can include Num Slots parameter and specific Leg Names of Hashed Leg Names in their ping request:

<DistributionDirectives>
   <NumSlots>5</NumSlots>
   <Directive Action="Include"><Name>Leg1</Name></Directive>
   <Directive Action="Include"><HashName>SGu5F6yVHnhC</HashName></Directive>
</DistributionDirectives>

Then in the ping response, they will receive the list of legs that were requested with their bids:

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Result Value="BaeOK">
        <TransactionID>E302B95D-4E1B-4BC3-98EB-CD80923879E9</TransactionID>
        <Bid0>
            <Legname>Leg1</Legname>
            <Payout>8.50</Payout>
            <Status>Success</Status>
        </Bid0>
        <Bid1>
            <HashLegname>SGu5F6yVHnhC</HashLegname>
            <Payout>0.0</Payout>
            <Status>Buyer not found</Status>
        </Bid1>
    </Result>
</Response>

If there are no eligible campaigns in the leg requested by publisher, the error message will be sent: Buyer not found.

Code examples on post

On the post, publishers must indicate legs, to which they expect to sell the lead:

<DistributionDirectives>
   <Numslots>0</Numslots>
   <Directive Action="Include"><Name>Leg1</Name></Directive> 
   <Directive Action="Include"><Name>Leg2</Name></Directive>
</DistributionDirectives>

In the post response, they will receive the list of legs that were requested with the payout or error message if the lead wasn't sold to that leg:

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Result Value="BaeOK">
        <TransactionID>E302B95D-4E1B-4BC3-98EB-CD80923879E9</TransactionID>
        <Sale0>
            <Legname>Leg1</Legname>
            <Payout>0.00</Payout>
            <Status>Unable to monetize</Status>
        </Sale0>
        <Sale1>
            <Legname>Leg2</Legname>
            <Payout>5.95</Payout>
            <Status>Success</Status>
        </Sale1>
    </Result>
</Response>

Shared ping post flow

Shared ping post flow includes the following steps:

1. PX receives the ping request from the publisher with the lead that includes all vertical specific information without contact data.

Distribution directives block with num slots specified, as well as ZIP code and IP Address are mandatory, leg names and hashed leg names are optional parameters on ping.

2. If the publisher didn't specify any legs, PX determines the list of potential campaigns for this lead according to the lead flow.

3. In shared prediction flow, PX analyzes direct bids and payout rules of direct post campaigns.

4. In shared ping forwarding flow, PX forwards ping request to all shared campaigns and analyzes direct bids and bids of ping post campaigns based on real-time responses.

5. The PX bid is calculated per each leg (or per each leg requested by the publisher).

6. PX sends ping response to the publisher including PX bids per each leg (or per each leg requested by the publisher) and Transaction ID.

7. If PX wins the lead, the publisher sends the post request with the full lead info, Transaction ID, and specific names or hashed names of legs, to which the publisher expects to sell this lead.

If the post request doesn't include any leg names or hashed names, the lead won't be accepted and publisher will receive an error message: Mandatory parameter is missing, lead cannot pass validation.

8. PX tries to sell the lead to shared campaigns within the legs specified.

9. If the lead is sold to campaign(s), PX sends post response to the publisher with payouts per each leg.

11. If the lead is not sold to some legs, the corresponding error per each leg is sent to the publisher (e.g. Unable to monetize).

Follow this article for more details about Shared Bid calculation.

Leg naming

Shared ping and post responses can be sent to the publisher using leg names or hashed leg names.

To configure this, go to publisher settings and click the pencil icon to edit General settings. Navigate to Leg naming field and select Legname of Hashed Legname, depending on your preferences:

Hashed Legname is selected by default.

Margin per leg

In shared ping post, you can also set publisher margin or fixed pricing per each leg. This is a useful option when you have campaigns within the leg that buy many leads from this publisher on a regular basis. You can increase the margin for this particular leg to engage this publisher in selling shared leads to this leg.

In this case, when the publisher sells the lead to the leg, margin or fixed pricing set per this leg will be applied for this lead instead of general publisher settings.

To configure this, follow instructions in publisher settings article.

When Fixed pricing is enabled for the publisher, on the ping stage of Margin per leg ping post flow, if the highest bid received from buyer campaigns is lower than Fixed Price*Bid Floor amount, Margin % is applied to this lead instead of Fixed price configured.