SmartApi with Ad Generation Rules

smartApiAdGenRules.md

SmartAPI: Let's say we already configured SmartAPI for fetching data from any weather API. Now we've two configurations:

Config 1:

Now we uploaded the feed inside smartTag and Add Filters:

• AND Logic, selectors_data[city] contains 'Rome'
• AND Logic, selectors_data[city] contains 'Singapore'

That means only 'Rome' and 'Singapore' city weather will be fetch from the API.

Config 2:

We created the AdUnit, we'll now add Add AD generation Rules :

• AND Logic, selectors_data[weather] contains 'rain, rainy'
• AND Logic, selectors_data[weather] contains 'cloud, cloudy'
• AND Logic, selectors_data[weather] contains 'sunny, clear'

If we do above config, that means when we're creating variants - we need to create 6 varaints.

• city = 'Rome' AND weather ~= 'rain, rainy'
• city = 'Rome' AND weather ~= 'cloud, cloudy'
• city = 'Rome' AND weather ~= 'sunny, clear'
• city = 'Singapore' AND weather ~= 'rain, rainy'
• city = 'Singapore' AND weather ~= 'cloud, cloudy'
• city = 'Singapore' AND weather ~= 'sunny, clear'

Example 1: Weather

- Variant 1: City [Singapore]
    - title
    - description
    - custom_text_1 (e.g. from API: temperature)
    - custom_text_2 (e.g. from API: weatherType)
    - custom_text_3 (e.g. from API: city)
    - custom_image_1
    - custom_image_2

    Macros
    - weatherType: 'sunny, clear' [Condition: contains]
    - city: singapore [Condition: equal]

- Variant 2: City [Singapore]
    - title
    - description
    - custom_text_1 (e.g. from API: temperature)
    - custom_text_2 (e.g. from API: weatherType)
    - custom_text_3 (e.g. from API: city)
    - custom_image_1
    - custom_image_2

    Macros
    - weatherType: 'cloud, cloudy' [Condition: contains]
    - city: singapore [Condition: equal]

- Variant 3: City [Minsk]
    - title
    - description
    - custom_text_1 (e.g. from API: temperature)
    - custom_text_2 (e.g. from API: weatherType)
    - custom_text_3 (e.g. from API: city)
    - custom_image_1
    - custom_image_2

    Macros
    - weatherType: 'rain, rainy' [Condition: contains]
    - city: minsk [Condition: equal]

Ad Serving Logic

• We need to add connecting macro in SmartTag. In this case, it's city.

Option 1: Geo Targeting

• If enabled, it'll ask browser permission to share location.
  • if shared, we'll get lat/long of user and from lat/long find the city from our IP database
  • if not shared, we'll get the IP address and get city from our IP database

Option 2: Smart Macro %g

• if selected from "SMART MACRO" in AdUnit level, we'd expect city, country, zip from DV360 ad server. Based on the city code we'll find the city name do the match.

Option 3: Nothing selected

• we'll take user's IP address and get the city name from our IP database.

let's say option 1 is enabled for now. So, from browser location sharing we got "singapore" as the city. So, we'll find the necessary data from SmartTag API pages. Let's assume, the data from API is showing singapore is having temparature 30 degree with weather type as "cloudy". So, we'll show the Variant 2 in this case..

Example 2: Stock API

- Variant 1: Category: 'Food'
    - title
    - description
    - custom_text_1 (e.g. from API: category)
    - custom_text_2 (e.g. from API: price)
    - custom_text_3 (e.g. from API: stockName)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 111 [Condition: Equal] (default)
    - category: 'food' [Condition: Equal]

- Variant 1: Category: 'Entertainment'
    - title
    - description
    - custom_text_1 (e.g. from API: category)
    - custom_text_2 (e.g. from API: price)
    - custom_text_3 (e.g. from API: stockName)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 222 [Condition: Equal] (default)
    - category: 'entertainement' [Condition: Equal]

Ad Serving Logic

• Here, the SmartTag connecting macro is "LINE_ITEM" and value is "category".
• For this example, from CampaignManager we'll receive line=<?>
• based on the line value (e.g. 222) we know, server is asking for which (e.g. 222 = "entertainment") category.
• Then, we'll get a variant of "entertainment" category and show in the template

Example 3: Football (LFC vs MANU)

- Variant 1: LFC Wins
    - title
    - description
    - custom_text_1 (e.g. from API: score)
    - custom_text_2 (e.g. from API: StadiumName)
    - custom_text_3 (e.g. from API: result)
    - custom_image_1
    - custom_image_2

    Macros
    - result: 'H' [Condition: Equal] (default)

- Variant 2: MANU Wins
    - title
    - description
    - custom_text_1 (e.g. from API: score)
    - custom_text_2 (e.g. from API: StadiumName)
    - custom_text_3 (e.g. from API: result)
    - custom_image_1
    - custom_image_2
    
    Macros
    - result: 'A' [Condition: Equal] (default)

- Variant 3: Match Draw
    - title
    - description
    - custom_text_1 (e.g. from API: score)
    - custom_text_2 (e.g. from API: StadiumName)
    - custom_text_3 (e.g. from API: result)
    - custom_image_1
    - custom_image_2

    Macros
    - result: 'D' [Condition: Equal] (default)

Ad Serving Logic

• while setting the SmartTag, we'll add connecting macros. It'l' show as "MACROS" in smartTag edit page.
• for this API, we'll select result as connecting macro.
• Our system will find the API page where result = 'H'. Then, based on that will match Variant 1 to show.

Problems:

• Need to find an API where they return which team won the match or the result of the match. not just the score.

To clarify the logic.. line item only have 2 ID, Singapore or Rome. So the correct logic should be
Variant 1: city = [Rome], tempareture > 30, LINE_ITEM = 1
Variant 2: city = [Rome], tempareture < 30, LINE_ITEM = 1
Variant 3: city = [Rome], tempareture = 30, LINE_ITEM = 1
Variant 4: city = [Singapore], tempareture > 30, LINE_ITEM = 2
Variant 5: city = [Singapore], tempareture < 30, LINE_ITEM = 2
Variant 6: city = [Singapore], tempareture = 30, LINE_ITEM = 2

So when Line_item=2 is passed in, (Or for future implementation using geo.)

Then Variant 4 or 5 or 6 will show depends on the current temperature.

Hope it make sense.

Got it. This seems fine. Will work on it. @reiro WDYT?

@imtiaz-emu

Config 1: For smart tag I think it should be
OR Logic, selectors_data[city] contains 'Rome'
OR Logic, selectors_data[city] contains 'Singapore'

Config 2: @travis got your comment.

1. city parameter we got from user location (geo) or from IP, right?
2. temperature value is already present at our pages data
3. LINE_ITEM - As I understand LINE_ITEM is weather_type or some other targeting coming from display network? Will get it through params.

Now about matching. SmartTagFilter has body (value) and condition type (equal, more them, less then etc).
Macro has only value right now without condition. To make it work with temperature (<, >, >=, <= etc) we should think about:

1. use filters table as AD generation Rules. In this case it will load database each time make more queries to database to fetch not only ads macros, but also ads filters.
2. WDYT about handling condition matching directly on macro side. like add new field condition_type. By default it will be equal. (to match city, or line item etc). But it can be (<, >, <=, >=) etc
   Another option is to have a rule, that if macro value contains condition sign (<, > ...) before the value - it will be parsed and transformed into a logical rule to match.

Anyway lets discuss it today in skype. I think I have to do the same thing about macro rules for Porsche campaign 👍

There should be 2 ways to get city: via Line Item macro or through geo targeting (separate task). So line item is to define city as well.

Prefer conditional matching at ad macro level.

HI guys,

Just to describe the different scenarios Smart API will work:

Scenario 1:

1. Able to show different variants based on the weather of different cities:
   For .e.g., If Singapore is raining, it will show a image of rain, with the temperature and "Rainy".
   See example: https://richmediagallery.com/detail?id=13213

2. Able to show different variants based on Premier League Match result:
   For e.g., If Liverpool v.s. Manchester match, and
   If Liverpool win, then a banner will show "Well done Liverpool" showing Liverpool Jersey" and scoreline/
   If Liverpool lose, then a banner will show " No worries Liverpool. You'll never walk alone".
   If Draw, then a banner will show " Not bad" and scoreline.
   See example: https://flashtalkingshowcase.com/campaigns/90

3. Able to show latest covid situation, if covid > 1000 case per day, show a banner asking people to stay indoor. if covid < 1000, show a banner to wash their hand.

SmartAPI:

Example 1: Football (LFC vs MANU)

- Variant 1: LFC Wins
    - title
    - description
    - custom_text_1 (e.g. from API: score)
    - custom_text_2 (e.g. from API: StadiumName)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 111 [Condition: Equal] (default)

- Variant 2: MANU Wins
    - title
    - description
    - custom_text_1 (e.g. from API: score)
    - custom_text_2 (e.g. from API: StadiumName)
    - custom_image_1
    - custom_image_2
    
    Macros
    - LINE_ITEM: 222 [Condition: Equal] (default)

- Variant 3: Match Draw
    - title
    - description
    - custom_text_1 (e.g. from API: score)
    - custom_text_2 (e.g. from API: StadiumName)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 333 [Condition: Equal] (default)

Ad Serving Logic

• For this example, from CampaignManager we'll receive line=<?>
• based on the line value we'll fetch Variant from Ad > Macro > LINE_ITEM
• That means, LINE_ITEM going to be a default Macro for each Variant.

Problems:

• It's only a single match. Let's say we want to show Premier league results.
  20 teams, 10 macthes each week, 3 possible outcomes per match = 103 = 30 variants (if we want to show match based ad)
  20 teams, 3 possible outcomes per team = 203 = 60 variants (if we want to show team based ad)

Example 2: Weather

- Variant 1: City [Singapore]
    - title
    - description
    - custom_text_1 (e.g. from API: temperature)
    - custom_text_2 (e.g. from API: weatherType)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 111 [Condition: Equal] (default)
    - temperature: 30 [Condition: greater than]
    - city: singapore [Condition: equal]

- Variant 2: City [Singapore]
    - title
    - description
    - custom_text_1 (e.g. from API: temperature)
    - custom_text_2 (e.g. from API: weatherType)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 111 [Condition: Equal] (default)
    - temperature: 30 [Condition: less than]
    - city: singapore [Condition: equal]

- Variant 3: City [Minsk]
    - title
    - description
    - custom_text_1 (e.g. from API: temperature)
    - custom_text_2 (e.g. from API: weatherType)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 222 [Condition: Equal] (default)
    - temperature: 30 [Condition: greater than]
    - city: minsk [Condition: equal]

Ad Serving Logic

• For this example, from CampaignManager we'll receive line=<?>
• based on the line value we'll fetch Variant from Ad > Macro > LINE_ITEM
• That means, LINE_ITEM going to be a default Macro for each Variant.

lets say, line=111 is passed, We'll get 2 variants (1,2). Except LINE_ITEM, we have two different macros.
based on temperature and city we'll find a match from SmartAPI > Pages.

Example 3: COVID-19

- Variant 1: No. of Cases
    - title
    - description
    - custom_text_1 (e.g. from API: numberOfCases)
    - custom_text_2 (e.g. from API: cityName)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 111 [Condition: Equal] (default)
    - numberOfCases: 1000 [Condition: greater than]
    - city: singapore [Condition: equal]

- Variant 2: No. of Cases
    - title
    - description
    - custom_text_1 (e.g. from API: numberOfCases)
    - custom_text_2 (e.g. from API: cityName)
    - custom_image_1
    - custom_image_2

    Macros
    - LINE_ITEM: 111 [Condition: Equal] (default)
    - numberOfCases: 1000 [Condition: less than]
    - city: singapore [Condition: equal]

Ad Serving Logic

• For this example, from CampaignManager we'll receive line=<?>
• based on the line value we'll fetch Variant from Ad > Macro > LINE_ITEM
• That means, LINE_ITEM going to be a default Macro for each Variant.

WDYT?

Hi Imtiaz,

Think of scenario where there is no line item. That means the variants logic should not dependent of the line item from Google. Line Item is only use when we need to serve different variants targeting different audience from Google

In the above 3 scenarios, all should not use the logic from google.

That means for the soccer e.g., the API should able to indicate which team won the match. so that it will match the variant and show.

For weather, it will only depends on City and should not have Line_Item

same for Covid, Line_item is irrelevant in this scenario as well.

Let's say, some football API returns this data:

{
      "name": "Matchday 1",
      "matches": [
        {
          "date": "2015-08-08",
          "team1": "Manchester United FC",
          "team2": "Tottenham Hotspur FC",
          "score": {
            "ft": [
              1,
              0
            ]
          }
        },
        {
          "date": "2015-08-08",
          "team1": "AFC Bournemouth",
          "team2": "Aston Villa FC",
          "score": {
            "ft": [
              0,
              1
            ]
          }
        }
      ]
    }

So, in our SmartTag - we'll create 2 pages as there are 2 matches between 4 different teams. In each page, there will be team1, team2, result.

Now, in our Ad Level, we need to create variants. We can create variants like:

• Variant 1: Manchester United FC win, show images, score, opponent
• Variant 2: Aston Villa FC win, show images, score, opponent
• Variant 3: Manchester United FC draw, show images, score, opponent
• Variant 4: Aston Villa FC lose, show images, score, opponent
• etc...

So, when our Ad is going to serve - we need a connection parameter that will connect both the variants and the pages. That's why I proposed line as a connection parameter. Consider the following case:
If we always want to show the win variants - then which team win will show? Here, both Manchester United FC, Aston Villa FC wins. If we pick random, then no need for a connection parameter.

Same goes for COVID or Weather API.

To summarise, if we don't use any connecting parameter, then we have to show random variants.

As you can see, different API examples (COVID, Weather, Stock, Football, Cricket etc.) or scenarios have different use cases. We have to come to a generalise solution that will work for all cases - that's why I'm trying to discuss. Otherwise, we need to customize for every API scenarios.

Yes. Agree with the connection parameter. But probably should not use line, cos line is based on the value coming in from ad server. That means when setup the API, we should define what is the connection parameter. Connection parameter can be "Geo" "City" "Zip", time of day, day of week.

For the case of football match, for this particular scenario, we just need to pass in one match info. That means if we want to create multiple matches, then we will create separate ad units.

  "matches": [
    {
      "date": "2015-08-08",
      "team1": "Manchester United FC",
      "team2": "Tottenham Hotspur FC",
      "score": {
        "ft": [
          1,
          0
        ]
      }
    },

For Covid or Weather API, we will need the city as connector parameter.