Integrations

SpikeCom offers multiple ad and placement types to serve.

Supported Placement Types

• Main Banner
• Strip Banner
• Products
• Search
• Brand
• Popup
• Push Notification
• Content Card
• Carousal
• Other

Integration Type

Three commonly used integration options are available to you, which can support minor variations to suit your individual needs.

1. JSON API
2. JS
3. IFrame

Workflow

1. Create Product Catalogs from 'Product' module which will allow selection of these products from Advertiser end at time of Ad-Item creation inside a Campaign. (This step is required for placement object type 'Product' and 'Search'.
2. Create Brand Catalogs from 'Brand' module which will allow selection of these brands from Advertiser end at time of Ad-Item creation inside a Campaign. (This step is required for placement object type 'Top-Listing'.
3. Create Placement from 'Placement' module. Select object type , in case if object type is 'Push Notification' or 'Content Card', you can choose 'Integration Type' as well, currently we support 'One-Signal' integration for push notifications & content card placements to automatically send notifications. For Carousal type of placement you have to specify no of slides/slots it has on your page out of 9, since different advertisers can book different slots. For Search type of placement you have to specify specific keyword limit , this is the limit of max no of keywords allowed for an advertiser to give against their products for any date on this search placement, this same keywords cannot be used by other advertisers for this same date on this placement.
Spcify the decided financial rates of this placement based on different supported payout models (CPM / CPC / CPD / CPW).
4. Spike agents will create a quotation for advertiser from Quotations module and send it forward for advertiser acceptance. Advertiser after recieving notification for it will have to review the quotation and upload a PO against it and send further for review. This will then recieve to spike admins who will have to review the uploaded PO and after their acceptance the quotation becomes finalized.
5. Advertiser / Spike Admins can now create Booking plans against that approved quotations and send for financial review and approval. Spike finance team will have to review this booking plan and all publisher booking orders in it and approve/refuse them. After their approval these booking orders are sent towards publisher for approval.
6. Publisher after receiving this notification will have to go to Approval Requests page and open this booking plan and either accept / reject. Once publisher accepts this booking order advertisers then can create campaign against this plan.
7. Advertiser can now see this placement while creating any new campaigns and its ads. Upon choosing relevant placement some configuration options will vary , like for placement object type 'search' and 'product' all products added against this publisher in step 1 will be available for selection as meta data. for placement object type 'push notification' and 'content card' image creative is optional and meta data 'Title & Message' or 'Title & Description' will become mandatory input fields.
8. Advertiser will publish the ads created and then this campaign goes towards publisher for final acceptance to perform a sanity check and accept.
9. This campaign will now appear for Publisher which he can accept or reject after reviewing. After acceptance of campaign from Publisher , campaign and it's ads will come in Running status on there start date.
10. Publisher can now use 'Generate Placement Tag' option in Placement List module against this placement this is a one time process which will get them the ads served in any of following three possible manners,
1. JSON
2. JS
3. IFrame

JS & IFrame types can be used directly, simply copy the placement tag and paste it in your application where you want ad to be served.

JSON AD API Details:

For JSON, simply copy the placement tag, modify the url and replace "(enter your api access key here)" with the access key which can be fetched from 'Settings', you can add multiple filter options here to get the ads in response accordingly. For the list of available filter options, please refer to "Serve" API details below in order to check how the system decides on which ads to serve refer to section "Ads Serving & Refresh Logic". Once you are done with the JSON AD API Request URL modification, place it on your page load and from the ads responded you can display them on your page as you want.

In case of JSON , whenever the JSON AD API Request URL is called we register an impression for all responded ads, but for subsequent impressions without refresh/page-load i.e for example upon scrolling, publisher shall use our 'viewable_url' callback api where as 'eligible_url' callback api is only at pageload to register impressions accordingly, similarly for registering clicks, publisher shall use our 'redirect_url' to register clicks. Value of these fields can be found against each ad in our JSON AD API Response.

Following Api's are supported/involved in Spike Com Ad-Serving,

1. Serve
2. Viewable impression
3. Eligible impression
4. Click register
5. Aquisition
6. Add To Cart

1. Serve:

This is taken from 'Get Placement Tag' link of Placements grid and the snippet can then be used to serve ads.

It has following properties,

Sample Call

*- placementID & type are mandatory to supply where as other properties are optional for further filtration.

*- placementID can be found for any placement by viewing it and picking the last portion from the url as highlighted below.

Response for Json API

*- In case if type = json is used the response will be as below, the values will vary based on the serving ad.

    {
        "status":"success",
        "lang":"Default",
        "adItems":[
            {
                "ad_Id":"YOUR_AD_ID",
                "placement_Id":"YOUR_SELECTED_PLACEMENT_ID",
                "placementGroup_Id":"YOUR_SELECTED_PLACEMENT_GROUP_ID",
                "serving_priority":1,
                "ad_metaData":[
                    
                ],
                "width":300,
                "height":250,
                "responsive":false,
                "ad_title":"Placement 3 Ad # 2",
                "alt_text":"",
                "target":"_blank",
                "tracking_pixel_url":"",
                "body":"",
                "redirect_url":"https://api-sandbox.spikecom.net/api/adserve/clickregister/?placementID=YOUR_SELECTED_PLACEMENT_ID&adID=YOUR_AD_ID",
                "destination_url":"",
                "refresh_url":"https://api-sandbox.spikecom.net/api/adserve/refresh/?placementID=YOUR_SELECTED_PLACEMENT_ID&type=json",
                "refresh_time_ms":0,
                "image_url":"https://ads-spike-nonprod.azureedge.net/media/YOUR_MEDIA_FILENAME_AND_EXTENSION",
                "lang":"Arabic",
                "per_user_limit":null,
                "daily_limit":null,
                "viewable_url":"https://api-sandbox.spikecom.net/api/adserve/viewableimpression/?placementID=YOUR_SELECTED_PLACEMENT_ID&adID=YOUR_AD_ID",
                "eligible_url":"https://api-sandbox.spikecom.net/api/adserve/eligibleimpression/?placementID=YOUR_SELECTED_PLACEMENT_ID&adID=YOUR_AD_ID",
                "unique_delivery":false,
                "adStartDate":"02/16/2022",
                "adEndDate":"02/20/2022",
                "adTargetAgeGroup":"",
                "adTargetGender":null,
                "adTargetGeoLocation":"40.7324319 -73.82480777777776",
                "adTargetGeoRadius":500,
                "campaignStartDate":"02/16/2022",
                "campaignEndDate":"02/20/2022"
            }
        ]
    }

Response Definition

lang (Language):

This is an optional field , possible values is one from below, based on the supplied value the ad's having creative with this language will be served only.

dk (Datakeys):

Data-keys can be created against publishers from Targets window and Rules can be set on those keys from Data-Key-Segments window.

These data-keys can be supplied to further filter ads and serve only those ad's which have any Target Segment fulfilling the specified rule.

Sample usage:

Notice how age and gender data-keys were supplied, even when we already have predefined set of filters for that like ageGroup and gender which is defined at ad level directly, so it's actually pointless to define such data-keys , instead some other data keys can be defined and used. Note that the data-key filters are different and if specified will only be searched in ad's target segments fulfilling the specified rule while calling it and data-key property values will not be compared with any existing field of ad.

2. Viewable Impression:

This end point is used to register a viewable impression whenever the ad comes in view-port completely.

It has following properties,

Sample Call:

Response:

Response will have a json indicating response code for success or failures with error or success message.

    {
        succeeded: true,
        code: 200,
        result: "Impression successfully registered.",
        exceptionType: "",
        errors: [ ]
    }

3. Eligible Impression:

This end point is used to register an eligible impression whenever the ad is served.

It has following properties,

Sample Call

Response

Response will have a json indicating response code for success or failures with error or success message.

    {
        succeeded: true,
        code: 200,
        result: "Impression successfully registered.",
        exceptionType: "",
        errors: [ ]
    }

4. Click Register

This end point is used to register a click whenever the ad is clicked on.

It has following properties,

Sample Call

Response

Response will have a json indicating response code for success or failures with error or success message.

    {
        succeeded: true,
        code: 200,
        result: "Click successfully registered.",
        exceptionType: "",
        errors: [ ]
    }

5. Aquisition Register

This end point is used to register a conversion/aquisition.

It has following properties,

Sample Call

Response

Response will have a json indicating response code for success or failures with error or success message.

    {
        succeeded: true,
        code: 200,
        result: "Aquisition successfully registered.",
        exceptionType: "",
        errors: [ ]
    }

6. Add to Cart Register

This end point is used to register an 'add-to-cart' type of transaction.

It has following properties,

Sample Call

Response

Response will have a json indicating response code for success or failures with error or success message.

    {
        succeeded: true,
        code: 200,
        result: "Aquisition successfully registered.",
        exceptionType: "",
        errors: [ ]
    }

Apart from above API's there are some other API's as well that we support can help in integration which are as follows,

Placement Hierarchy API

This end point is used to respond with all the placements of a publisher.

It has following properties,

Sample Call

Response

Response will have a Json for all placements of that publisher.

    [
        {
            "noOfCampaigns":3,
            "placementId":"YOUR_PLACEMENT_ID",
            "placementTitle":"Placement Title",
            "placementType":"Standard",
            "objectType":"banner",
            "publisherId":"YOUR_PUBLISHER_ID",
            "publisherName":"Publisher Name",
            "placementSize":"300x250",
            "placementSizeHeight":250,
            "placementSizeWidth":300,
            "responsiveEnabled":true,
            "placementGroupId":"YOUR_PLACEMENT_GROUP_ID",
            "placementGroupName":"Banner",
            "cpdRate":0.0,
            "cpmRate":1.0,
            "metaData":[
                {
                    "key":"mobile_placements",
                    "value":"home_banner",
                    "language":null
                },{
                    "key":"mobile_screens",
                    "value":"home",
                    "language":null
                }
            ],
            "multipleAdvertisersAllowed":true,
            "positionPriority":1,
            "isCampaignSpace":true,
            "status":"Active",
            "createdOn":"2022-04-05T06:25:51.218Z"
        },{
            "noOfCampaigns":1,
            "placementId":"YOUR_PLACEMENT_ID",
            "placementTitle":"Placement Title",
            "placementType":"Standard",
            "objectType":"strip",
            "publisherId":"YOUR_PUBLISHER_ID",
            "publisherName":"Publisher Name",
            "placementSize":"180x150",
            "placementSizeHeight":150,
            "placementSizeWidth":180,
            "responsiveEnabled":true,
            "placementGroupId":"YOUR_PLACEMENT_GROUP_ID",
            "placementGroupName":"Strip Banner",
            "cpdRate":0.0,
            "cpmRate":0.0,
            "metaData":[
                {
                    "key":"mobile_placements",
                    "value":"home_strip_banner",
                    "language":null
                },{
                    "key":"mobile_screens",
                    "value":"home",
                    "language":null
                },{
                    "key":"position",
                    "value":"1",
                    "language":null
                }
            ],
            "multipleAdvertisersAllowed":true,
            "positionPriority":2,
            "isCampaignSpace":true,
            "status":"Active",
            "createdOn":"2022-04-05T06:27:12.459Z"
        }
    ]
    

Brands API

This end point is used to respond with all the brands of a publisher.

It has following properties,

Sample Call

Note: publisherId or placementId either one of them can be supplied in order to get all brands of a publisher.

Response

Response will have a Json for all brands of that publisher.

    [
        {
            "key":"BRAND_UNIQUE_KEY",
            "brand":"Oppo",
            "category":"Mobiles Phones",
            "description":"Mobile, Tablets and Other Brand",
            "keywords":["Mobiles Phones","Oppo","Android Mobiles"],
            "language":"English",
            "location":"All over the world",
            "longitude":40.0,
            "lattitude":30.0
        },{
            "key":"BRAND_UNIQUE_KEY",
            "brand":"J.",
            "category":"Perfumes",
            "description":"Clothing Brand",
            "keywords":["Perfumes","J.Brand","J."],
            "language":"Urdu",
            "location":"Karachi, Lahore, Islamabad",
            "longitude":50.0,
            "lattitude":60.0
        },{
            "key":"BRAND_UNIQUE_KEY",
            "brand":"Oppo",
            "category":"Mobiles Phones",
            "description":"Mobile, Tablets and Other Brand",
            "keywords":["Mobiles Phones","Oppo","Android Mobiles"],
            "language":"English",
            "location":"All over the world",
            "longitude":40.0,
            "lattitude":30.0
        }
    ]
    

Product Streamline API

This end point is used to upload new or update existing products of a publisher.

Type : POST

It has no parameters,however In the body add a gzip compressed file in which should be a json originally in the following format , where specify api access key of your publisher account against "ApiKey" and add all the products against "Products" field array , sample share below,,

    
        {
			"ApiKey": "YOUR_API_ACCESS_KEY",
			 
			 "Products": [ 
			{ 
				"Sno": "YOUR_PRODUCT_UNIQUE_IDENTIFIER", 
				"Language": "YOUR_PRODUCT_PRIMARY_LANGUAGE", 
				"Barcode": "YOUR_PRODUCT_BARCODE", 
				"SKU": "YOUR_PRODUCT_SKU", 
				"ProductName": "YOUR_PRODUCT_NAME_IN_PRIMARY_LANGUAGE", 
				"Category": "YOUR_PRODUCT_CATEGORY_IN_PRIMARY_LANGUAGE", 
				"Brand": "YOUR_PRODUCT_BRAND_IN_PRIMARY_LANGUAGE",
				"Branch": "YOUR_PRODUCT_BRANCH_IN_PRIMARY_LANGUAGE",				
				"Keywords": "YOUR_PRODUCT_GENERIC_KEYWORDS_IN_PRIMARY_LANGUAGE", 
				"ImageUrl": "YOUR_PRODUCT_IMAGE_URL", 
				"Price": "YOUR_PRODUCT_PRICE", 
				"IsEnabled": "TRUE OR FALSE", 
				"InStock": "TRUE OR FALSE", 
				"DiscountedPrice": "YOUR_PRODUCT_DISCOUNTED_PRICE", 
				"ProductId": "YOUR_PRODUCT_ID", 
				"BranchId": "YOUR_PRODUCT_BRANCH_ID", 
				"BrandId": "YOUR_PRODUCT_BRAND_ID", 
				"CategoryId": "YOUR_PRODUCT_CATEGORY_ID", 
				"LanguageOverrides": [
					{
					"Language" : "YOUR_PRODUCT_SECOND_LANGUAGE", 
					"ProductName" : "YOUR_PRODUCT_NAME_IN_SECOND_LANGUAGE",
					"Branch": "YOUR_PRODUCT_BRANCH_NAME_IN_SECOND_LANGUAGE",
					"Brand" : "YOUR_PRODUCT_BRAND_NAME_IN_SECOND_LANGUAGE",
					"Category" : "YOUR_PRODUCT_CATEGORY_NAME_IN_SECOND_LANGUAGE",
					"Keywords" : "YOUR_PRODUCT_GENERIC_KEYWORDS_IN_SECOND_LANGUAGE",
					"ImageUrl" : "YOUR_PRODUCT_IMAGE_URL_IN_SECOND_LANGUAGE",
					},
					{
					"Language" : "YOUR_PRODUCT_THIRD_LANGUAGE", 
					"ProductName" : "YOUR_PRODUCT_NAME_IN_THIRD_LANGUAGE",
					"Branch": "YOUR_PRODUCT_BRANCH_NAME_IN_THIRD_LANGUAGE",
					"Brand" : "YOUR_PRODUCT_BRAND_NAME_IN_THIRD_LANGUAGE",
					"Category" : "YOUR_PRODUCT_CATEGORY_NAME_IN_THIRD_LANGUAGE",
					"Keywords" : "YOUR_PRODUCT_GENERIC_KEYWORDS_IN_THIRD_LANGUAGE",
					"ImageUrl" : "YOUR_PRODUCT_IMAGE_URL_IN_THIRD_LANGUAGE",
					}					
					]
				
			}, 
			{ 
				"Sno": "YOUR_PRODUCT_UNIQUE_IDENTIFIER", 
				"Language": "YOUR_PRODUCT_PRIMARY_LANGUAGE", 
				"Barcode": "YOUR_PRODUCT_BARCODE", 
				"SKU": "YOUR_PRODUCT_SKU", 
				"ProductName": "YOUR_PRODUCT_NAME_IN_PRIMARY_LANGUAGE", 
				"Category": "YOUR_PRODUCT_CATEGORY_IN_PRIMARY_LANGUAGE", 
				"Brand": "YOUR_PRODUCT_BRAND_IN_PRIMARY_LANGUAGE",
				"Branch": "YOUR_PRODUCT_BRANCH_IN_PRIMARY_LANGUAGE",				
				"Keywords": "YOUR_PRODUCT_GENERIC_KEYWORDS_IN_PRIMARY_LANGUAGE", 
				"ImageUrl": "YOUR_PRODUCT_IMAGE_URL", 
				"Price": "YOUR_PRODUCT_PRICE", 
				"IsEnabled": "TRUE OR FALSE", 
				"InStock": "TRUE OR FALSE", 
				"DiscountedPrice": "YOUR_PRODUCT_DISCOUNTED_PRICE", 
				"ProductId": "YOUR_PRODUCT_ID", 
				"BranchId": "YOUR_PRODUCT_BRANCH_ID", 
				"BrandId": "YOUR_PRODUCT_BRAND_ID", 
				"CategoryId": "YOUR_PRODUCT_CATEGORY_ID", 
				"LanguageOverrides": [
					{
					"Language" : "YOUR_PRODUCT_SECOND_LANGUAGE", 
					"ProductName" : "YOUR_PRODUCT_NAME_IN_SECOND_LANGUAGE",
					"Branch": "YOUR_PRODUCT_BRANCH_NAME_IN_SECOND_LANGUAGE",
					"Brand" : "YOUR_PRODUCT_BRAND_NAME_IN_SECOND_LANGUAGE",
					"Category" : "YOUR_PRODUCT_CATEGORY_NAME_IN_SECOND_LANGUAGE",
					"Keywords" : "YOUR_PRODUCT_GENERIC_KEYWORDS_IN_SECOND_LANGUAGE",
					"ImageUrl" : "YOUR_PRODUCT_IMAGE_URL_IN_SECOND_LANGUAGE",
					},
					{
					"Language" : "YOUR_PRODUCT_THIRD_LANGUAGE", 
					"ProductName" : "YOUR_PRODUCT_NAME_IN_THIRD_LANGUAGE",
					"Branch": "YOUR_PRODUCT_BRANCH_NAME_IN_THIRD_LANGUAGE",
					"Brand" : "YOUR_PRODUCT_BRAND_NAME_IN_THIRD_LANGUAGE",
					"Category" : "YOUR_PRODUCT_CATEGORY_NAME_IN_THIRD_LANGUAGE",
					"Keywords" : "YOUR_PRODUCT_GENERIC_KEYWORDS_IN_THIRD_LANGUAGE",
					"ImageUrl" : "YOUR_PRODUCT_IMAGE_URL_IN_THIRD_LANGUAGE",
					}					
					]
				
			}
			
			 ]
			 
		}
		
            
    

Sample Call

Note: Product streamline api usage rate limit is 5 times per day.

Response

Based on unique combination of SKU , Language ,Price and BranchId the system will check for new and existing products , for all the new ones it will add them and for all the existing ones it will update them.

Product Deletion API

This end point is used to delete existing products of a publisher either by productId or by branchId.

Type : DELETE

sample body shared below,

					
					{ 
					"ApiKey": "YOUR_API_ACCESS_KEY", 
					"Products":[ 
					{ 
						"ProductId": "YOUR_PRODUCT_ID", 
						"BranchId": "YOUR_PRODUCT_BRANCH_ID" 
					}, 
					{ 	"ProductId": "YOUR_PRODUCT_ID",
						"BranchId": "YOUR_PRODUCT_BRANCH_ID" 
					} ] 
					}
					
				
				

When in products array a record with both productId and branchId is given it will delete that product for that branch only , When a record with only ProductId is given then it will delete that product only and for all branches and When a record with only BranchId given then it will delete all products from that branch.

Sample Call

Response

Based on the provided productId or branchId or combination of these system will delete those products.

JS & IFrame Details

When placement tag is used in the form of JS and IFrame , simply copying and pasting that tag in your placement of choice on supported platforms will result in serving of running ads on that placement.

In JS & IFrame eligible impression , viewable impression , clicks are all registered automatically and is handled by our server which is also responsible to serve ads as well as to track and record these transactions on the served ads, where as in order to track and record 'aquisition' or 'addToCart' type of transaction publisher must fetch data-attributes from the js & iframe response in which we create a parent 'div' element where the tag is used and serve our ad inside it.

This div have some data-attributes that we use and some that publisher can use like in order to track and record 'aquisition' and 'addToCart' type of transaction publisher must fetch and read 'data-aquisition-callback' and 'data-addToCart-callback' urls and make a call on these to make us register that kind of transaction. All other data-attributes are being used by our ad-serving platform itself to register and track other kinds of transactions.

Sample Request Tag for JS

<script type='text/javascript'>document.write('<script src="https://api-sandbox.spikecom.net/api/adserve/serve/?placementID=YOUR_PLACEMENT_ID&type=js&platform=YOUR_PLATFORM" type="text/javascript"></script>');</script>

 

Sample Request Tag for IFrame

<script type='text/javascript'>document.write('<script src="https://api-sandbox.spikecom.net/api/adserve/serve/?placementID=YOUR_PLACEMENT_ID&type=iframe&platform=YOUR_PLATFORM" type="text/javascript"></script>');</script>

                    

Response

Response will contain JS/IFrame serving running ads from our server.

Apart from above common integration options there are some sprcific to certain placement object types, understanding their configuration setup and integration can help in integrating those placements as well, which are as follows,

Carousal Placement Handling

Carousal is a special type of placement allowing user to create a placement of type carousal and define its slots/slides and then it can be used to serve different ads of various advertisers on different slots simultaneously if that slot is available for that day.

In this special type we allow selection of slot while creating an Ad-Item and 'slotNo' input paramater can be supplied in the ad-serving request call which will serve running ads on that slot.

For Js & IFrame , simply copy our placement tag after selecting the slotNo and then paste it inside the item div of each slide on your carousal type control. Just make sure the item div representing each slide on your carousal must have some 'id' defined on them and must be using class 'spikeCarousalAdSlot' in order for us to auto track clicks & impressions.

For Json , you can specify slotNo input as part of your ad-serving request call to our server , in response of which our server will serve you with running ads on that slot only. In case you want all running ads to be served irrespective of which slot they belong to then simply make a request call without slotNo input but with count value greater then or equal to total running ads on this placement so the server will serve you with all the running ads on this placement.

Sample Request Tag for Carousal

<script type='text/javascript'>document.write('<script src="https://api-sandbox.spikecom.net/api/adserve/serve/?placementID=YOUR_PLACEMENT_ID&type=YOUR_RESPONSE_TYPE&platform=YOUR_PLATFORM&slotNo=YOUR_SLOT_NO" type="text/javascript"> </script >');</script>

                    

Top-Listing Placement Handling

This kind of placement is allowed for multiple advertisers to book on same date, the way it works in the system is you need to create separate TopListing type placements for each slot in top listings in a single group like Placement 1: Top Listing Slot 1 (TopListing) Placement 2: Top Listing Slot 2 (TopListing) Placement 3: Top Listing Slot 3 (TopListing) for this simply go to 'Placements' module and create a new placement inside it in the Placement Page dropdown there's an option to create your own group click on it and name this group as your TopListing Group then specify all other values of your slot 1 on this top listing placement and save , in similar fashion create as many placements as you have slots in your top listing , make sure to select the same 'TopListing' group you created while creating first slot placement for the rest of slots as well and not create more groups..

For this to work , publisher must first define their supported Brands in Brand configuration.

Each advertiser when creating ads on these will only be able to select their own allowed brand. Once all brand ads are created and reviewed and approved in the ad-request api use 'groupPlacements=true' params to serve ads from all 3 slot placements in a single response. This can even further be customized if you want different top listings for different regions then you can create your custom key of regionId and create its different segment rules specifying to its different possible values and then in ad-creation these segments can be selected and in ad-request url append 'dk={"regionId":"1"}' to get all slot brands for region 1 only and 'dk={"regionId":"2"}' to get all slot brands for region 2..

Target Data keys and Target Data Segments are the section where you can create your custom targetting keys and rules. A group of rules in Spikecom system is called a segment. This will be useful if you wish to serve your ads differently based on regions or areas or cities or by any custom criteria. Simply go to Target Data Keys first and create your criteria key there like for example 'regionId' type string..

After defining the key you need to setup the rules on this key by which you will target different ads. For this go to Target Data Segments and create a new segment select your key and operator and value for example regionId is the key , '=' is the operator and '1' is the value. define all possible rules for this key i.e in our example for all regions.

Now simply go to Placements module and from the list click on 'Get Placement Tag' for any top listing slot placement and copy the generated tag. In the default generated tag replace '(enter your api access key here)' with your API access key which you can get from 'Settings' module also append '&groupPlacements=true' in order to get running ads in response from all slot placements inside this single 'TopListing' group that we created in step 1 while creating placements.

In order to recieve region wise ads differently you need to append your datakey params in the request as well like '&dk={regionId:1}' to serve ads that were marked with this rule segment. This way you can achieve different brand ads to be served at different slots for different regions.

Sample Request Tag for Top-Listing

<script type='text/javascript'>document.write('<script src="https://api-sandbox.spikecom.net/api/adserve/serve/?placementID=YOUR_PLACEMENT_ID&type=YOUR_RESPONSE_TYPE&platform=YOUR_PLATFORM&groupPlacements=true" type="text/javascript"> </script >');</script>

                    

Product/Sku Uplifting Handling

Any type of ad that allows products or brands selection will automatically contain the selected whole products in the ad response's meta data where the type is 'product'..

Also any custom meta key defined in the publisher configuration will allow us to define their prefix or default values at placement level , these meta keys and their default values will also be part of ad response's meta data where the type is 'userdefined' and the key will be what was set in publisher configuration..

For details please see "ad_metaData" in below sample response of an ad having products as well as custom meta keys defined for deeplinks as part of ad's meta data in response.

The selected products list is part of metavalue for 'product' type of meta data which is by-default in raw string format and has to be parsed into JSON first to process..

The combination of product type of meta data giving us all the selected product details and of all the default values of all custom meta keys can be used to generate custom deeplinks.

Sample Request Tag for Product

Response

					
	{
	"status": "success",
	"lang": "Default",
	"adItems": [{
			"ad_Id": "YOUR_AD_ID",
			"placement_Id": "YOUR_PLACEMENT_ID",
			"placementGroup_Id": "YOUR_PLACEMENT_GROUP_ID",
			"serving_priority": 1,
			"ad_metaData": [{
					"MetaKey": "YOUR_METADATA_ID",
					"MetaValue": "{\"catalogId\":null,\"id\":\"YOUR_METADATA_ID\",\"skuId\":\"YOUR_SKU_ID\",\"barcode\":\"YOUR_BARCODE_ID\",\"name\":\"YOUR_PRODUCT_NAME\",\"brand\":\"YOUR_BRAND_NAME\",\"category\":\"YOUR_PRODUCT_CATEGORY\",\"language\":\"YOUR_KEYWORDS_LANGUAGE\",\"keywords\":[\"YOUR_KEYWORDS\"],\"imageUrl\":\"YOUR_SKU_IMAGE_URL",\"IsFeatured\":\"true"}",
					"Language": "YOUR_METADATA_LANGUAGE",
					"Type": "product"
				},
				{
					"MetaKey": "YOUR_METADATA_ID",
					"MetaValue": "{\"catalogId\":null,\"id\":\"YOUR_METADATA_ID\",\"skuId\":\"YOUR_SKU_ID\",\"barcode\":\"YOUR_BARCODE_ID\",\"name\":\"YOUR_PRODUCT_NAME\",\"brand\":\"YOUR_BRAND_NAME\",\"category\":\"YOUR_PRODUCT_CATEGORY\",\"language\":\"YOUR_KEYWORDS_LANGUAGE\",\"keywords\":[\"YOUR_KEYWORDS\"],\"imageUrl\":\"YOUR_SKU_IMAGE_URL",\"IsFeatured\":\"true"}",
					"Language": "YOUR_METADATA_LANGUAGE",
					"Type": "product"
				},
				{
					"MetaKey": "YOUR_METADATA_ID",
					"MetaValue": "{\"catalogId\":null,\"id\":\"YOUR_METADATA_ID\",\"skuId\":\"YOUR_SKU_ID\",\"barcode\":\"YOUR_BARCODE_ID\",\"name\":\"YOUR_PRODUCT_NAME\",\"brand\":\"YOUR_BRAND_NAME\",\"category\":\"YOUR_PRODUCT_CATEGORY\",\"language\":\"YOUR_KEYWORDS_LANGUAGE\",\"keywords\":[\"YOUR_KEYWORDS\"],\"imageUrl\":\"YOUR_SKU_IMAGE_URL",\"IsFeatured\":\"false"}",
					"Language": "YOUR_METADATA_LANGUAGE",
					"Type": "product"
				}
			],
			"width": 300,
			"height": 250,
			"responsive": false,
			"ad_title": "Ad # 1",
			"alt_text": null,
			"target": null,
			"tracking_pixel_url": null,
			"body": "",
			"redirect_url": "https://api-sandbox.spikecom.net/api/adserve/clickregister/?placementID=YOUR_PLACEMENT_ID",
			"destination_url": "",
			"refresh_url": "https://api-sandbox.spikecom.net/api/adserve/refresh/?placementID=YOUR_PLACEMENT_ID&type=json",
			"refresh_time_ms": 0,
			"image_url": "",
			"lang": "",
			"per_user_limit": null,
			"daily_limit": null,
			"viewable_url": "https://api-sandbox.spikecom.net/api/adserve/viewableimpression/?placementID=YOUR_PLACEMENT_ID&adID=YOUR_AD_ID",
			"eligible_url": "https://api-sandbox.spikecom.net/api/adserve/eligibleimpression/?placementID=YOUR_PLACEMENT_ID&adID=YOUR_AD_ID",
			"unique_delivery": false,
			"adStartDate": "02/22/2022",
			"adEndDate": "02/24/2022",
			"adTargetAgeGroup": "",
			"adTargetGender": null,
			"adTargetGeoLocation": "40.7324319 -73.82480777777776",
			"adTargetGeoRadius": 500,
			"campaignStartDate": "02/22/2022",
			"campaignEndDate": "02/24/2022"
		}
		
	]
}
				
    

Search Placement Handling

To allow search type placements to be created having similar functionality as of product type inside placement and campaign modules, where as allow keywords & count based ad-serving from JSON AD API.

• Go to Placements and Create new placement.
• In Object type select 'Search' and fill rest of the fields and save, here for this type you will have to specify whats the max limit of specific keywords an advertiser can use for their products on any date with this search placement.
• There are two types of keywords associated with products , one defined as part of product definition by publisher themseleves these are considered as generic keywords and then another which are defined by advertisers during ad creation on these placements for their products these are considered as specific keywords.
• Now create a Campaign with this Publisher and then create an Ad in it.
• Upon selection of this Placement Group and then this 'Search' type Placement, system will allow Product's selection below which is mandatory here.
• All the Product SKU's defined against this Publisher from 'Products' window will be allowed for selection. Advertiser who is creating an ad will be choosing their own products.
• Once selection is done, all the Product SKU's related data will be tied to this AD in it's meta data.
• Advertisers can enter specific keywords now on these selected products under the limit set at placement configuraiton level.
• Complete the Ad by specifying all other fields and finishing it.
• After whole review-approval-publish-acceptance process is completed Ads would come in 'Running' state.
• Now go to Placement List window and against this search type placement click on 'Generate Tag'.
• Replace Publisher's API Access Key with this '(enter your api access key here)' in JSON AD API Request URL which is shown.
• In the API Request URL supply the entered value in the search bar by user against parameter 'kw' as shown below,

Sample Call

This will apply an additional filter of keywords on ads with the filters defined in filtration logic, i.e if placement type = product or search and kw parameter value is supplied, system will check for Ads having selected SKU's which have this value in their generic keywords or specific keywords and will respond with those Ads. Incase if the user entered keyword matches with generic keyword of one product and with specific keyword of another product then both products will be part of response, however the one matching with generic keyword will be responded back with "IsFeatured=false" where as the one matching with specific keyword will be responded back with "IsFeatured=true"

You can combine 'count' parameter with 'kw' to get as many ads in response as you want if it remains after filters are applied, where count if not given has a default value of 1 so 1 Ad will be served against single request , similarly count = 0 means all Ads will be served which remains after filters are applied.

Response

					
	{
	"status": "success",
	"lang": "Default",
	"adItems": [{
			"ad_Id": "YOUR_AD_ID",
			"placement_Id": "YOUR_PLACEMENT_ID",
			"placementGroup_Id": "YOUR_PLACEMENT_GROUP_ID",
			"serving_priority": 1,
			"ad_metaData": [{
					"MetaKey": "YOUR_METADATA_ID",
					"MetaValue": "{\"catalogId\":null,\"id\":\"YOUR_METADATA_ID\",\"skuId\":\"YOUR_SKU_ID\",\"barcode\":\"YOUR_BARCODE_ID\",\"name\":\"YOUR_PRODUCT_NAME\",\"brand\":\"YOUR_BRAND_NAME\",\"category\":\"YOUR_PRODUCT_CATEGORY\",\"language\":\"YOUR_KEYWORDS_LANGUAGE\",\"keywords\":[\"YOUR_KEYWORDS\"],\"imageUrl\":\"YOUR_SKU_IMAGE_URL",\"IsFeatured\":\"true"}",
					"Language": "YOUR_METADATA_LANGUAGE",
					"Type": "product"
				},
				{
					"MetaKey": "YOUR_METADATA_ID",
					"MetaValue": "{\"catalogId\":null,\"id\":\"YOUR_METADATA_ID\",\"skuId\":\"YOUR_SKU_ID\",\"barcode\":\"YOUR_BARCODE_ID\",\"name\":\"YOUR_PRODUCT_NAME\",\"brand\":\"YOUR_BRAND_NAME\",\"category\":\"YOUR_PRODUCT_CATEGORY\",\"language\":\"YOUR_KEYWORDS_LANGUAGE\",\"keywords\":[\"YOUR_KEYWORDS\"],\"imageUrl\":\"YOUR_SKU_IMAGE_URL",\"IsFeatured\":\"true"}",
					"Language": "YOUR_METADATA_LANGUAGE",
					"Type": "product"
				},
				{
					"MetaKey": "YOUR_METADATA_ID",
					"MetaValue": "{\"catalogId\":null,\"id\":\"YOUR_METADATA_ID\",\"skuId\":\"YOUR_SKU_ID\",\"barcode\":\"YOUR_BARCODE_ID\",\"name\":\"YOUR_PRODUCT_NAME\",\"brand\":\"YOUR_BRAND_NAME\",\"category\":\"YOUR_PRODUCT_CATEGORY\",\"language\":\"YOUR_KEYWORDS_LANGUAGE\",\"keywords\":[\"YOUR_KEYWORDS\"],\"imageUrl\":\"YOUR_SKU_IMAGE_URL",\"IsFeatured\":\"false"}",
					"Language": "YOUR_METADATA_LANGUAGE",
					"Type": "product"
				}
			],
			"width": 300,
			"height": 250,
			"responsive": false,
			"ad_title": "Ad # 1",
			"alt_text": null,
			"target": null,
			"tracking_pixel_url": null,
			"body": "",
			"redirect_url": "https://api-sandbox.spikecom.net/api/adserve/clickregister/?placementID=YOUR_PLACEMENT_ID",
			"destination_url": "",
			"refresh_url": "https://api-sandbox.spikecom.net/api/adserve/refresh/?placementID=YOUR_PLACEMENT_ID&type=json",
			"refresh_time_ms": 0,
			"image_url": "",
			"lang": "",
			"per_user_limit": null,
			"daily_limit": null,
			"viewable_url": "https://api-sandbox.spikecom.net/api/adserve/viewableimpression/?placementID=YOUR_PLACEMENT_ID&adID=YOUR_AD_ID",
			"eligible_url": "https://api-sandbox.spikecom.net/api/adserve/eligibleimpression/?placementID=YOUR_PLACEMENT_ID&adID=YOUR_AD_ID",
			"unique_delivery": false,
			"adStartDate": "02/22/2022",
			"adEndDate": "02/24/2022",
			"adTargetAgeGroup": "",
			"adTargetGender": null,
			"adTargetGeoLocation": "40.7324319 -73.82480777777776",
			"adTargetGeoRadius": 500,
			"campaignStartDate": "02/22/2022",
			"campaignEndDate": "02/24/2022"
		}
		
	]
}
				
    

Ad Serving and Auto Refresh Logic

When the placement tag is used, it sends a request to our server for serving an Ad against this placement, Ads are served from our server based on this logic. The Server then

• Fetches all 'Running' Ads against this placement.
• It filters from above Ads based on Day-Parting Logic i.e to keep those Ads only which have no day parting logic defined or have current hour-day inside it's day parting logic.
• It then removes all Ads from the above filtered list which are marked as Under-Performing and have Under Delivery Behavior set to "Stop".
• It then filters all Ads based on 'ageGroup' set on them and the supplied 'ageGroup' parameter if any in the request call to our server.
• It then filters all Ads based on 'gender' set on them and the supplied 'gender' parameter if any in the request call to our server.
• It then filters all Ads based on 'keywords' set on them and the supplied 'extraData' parameter if any in the request call to our server.
• It then filters all Ads based on 'longitutde' and 'lattitude' inside the given radius and checks if the supplied longitude and latitude falls inside it, if yes keeps those ads else filters them out.
• It then filters all Ads based on datakeys supplied in the request call to our server and those ads which have target segments assigned and have datakeys equal to the supplied datakeys then check what rule is set in that segment on that data key then matches the supplied key's value is in accordance with that rule then it keeps that ad else filters it out. Below is the logic for each rule-set Operator : "eq" , Logic: value for this key must be equal to the value in rule. Operator: "neq" , Logic: value for this key must not be equal to the value in rule. Operator : "lt" , Logic: value for this key must be less then to the value in rule. Operator: "lte" , Logic: value for this key must be less then or equal to the value in rule. Operator : "gt" , Logic: value for this key must be greater then to the value in rule. Operator: "gte" , Logic: value for this key must be greater then or equal to the value in rule. Operator : "sw" , Logic: value for this key must be starting with the value in rule. Operator: "ew" , Logic: value for this key must be ending with the value in rule. Operator: "con" , Logic: value for this key must contains the value in rule.
• It then filter Ads based on serving priority and their served count, in following manner, Lets say we have 3 Ads remaining in the filtered Ad list , 1 having serving priority = high , 2 having serving priority = medium and 3 having serving priority = low and each Ads are not yet served i.e their current served count = 0 , so in the first ad-serving call system will serve Ad # 1(high) , in second serving or refresh call system will again serve Ad # 1 (high), in third serving or refresh call system will again serve Ad # 1(high) , in fourth serving or refresh call system will serve Ad # 2(medium) , in fifth serving or refresh call system will serve Ad # 2(medium) , in sixth serving or refresh call system will serve Ad # 3(low) , so upon serving 6 times on this placement 1st 3 time it serves Ad#1 then 4th and 5th time it serves Ad#2 then 6th time it serves Ad#3 , meaning High Priority Ad Items will be served 3 times more then Low Priority Ad Items and Medium Priority Ad Items will be served 2 times more then Low Priority Ad Items.
• count: In the request for ad serving call there is an optional parameter 'count' (int) , it has default value = 1 if not supplied as well as for type = 'js' and 'iframe' it is defaulted to 1 , meaning 1 ad from the filtered remaining ones will be served in response to serve request and refresh request. for type = 'json' whatever count value is supplied , system will respond with that many ads if it finds that many ads after above filtration logic. (Note: Serving Priority and Serve Count filtration logic is not applicable in case of count is not equal to 1 and count is not defaulted to 1 i.e when count = some value other then 1 is supplied system will not filter ads based on their serving priority & serve count and will try to serve that many ads as asked if it finds that many ads after rest of filtration logic has been applied)
• groupPlacements: In the request for ad serving call there is an optional parameter 'groupPlacements' (boolean) which is to allow serving ads from multiple placements inside a single placement group , the group is identified from the placementId supplied.
• In the request for ad serving call some positive integer value for slotNo parameter was supplied and this placement is of type carousal , system will filter ads based on this slotNo input and only try to serve running ads on this slot.