hullcode

Hullcode Webpush Content Delivery Service API integration document

Use this document to integrate to our content delivery service for webpush notifications.

Before start, you must get in touch with our integration manager who will provide required keys for integration.

REQUEST

http://{SERVICE_HOST}:7012/request_content?partner_id={PARTNER_ID}&secret={SECRET}&subid={SUBID}&ip={USER_IP}&ua={USER_AGENT}&lang={USER_LANG}&tokenid={USER_ID}&days={USER_DAYS}&click_id={CLICK_ID}&ch-ua={SEC-CH-UA}&ch-uafull={SEC-CH-UA-FULL-VERSION}&ch-mobile={SEC-CH-UA-MOBILE}&ch-model={SEC-CH-UA-MODEL}&ch-platform={SEC-CH-UA-PLATFORM}&ch-platformv={SEC-CH-UA-PLATFORM-VERSION}&multiple={MULTIPLE_CAMPAIGNS}

Standard HTTP GET request

{SERVICE_HOST} should be replaced by the domain provided by the integration manager. We usually use specific domains for each partner.

PARAMETERS SPECIFICATION

partner_id={PARTNER_ID}
Value type
Integer. Mandatory
Description
Provided partner ID
Example
partner_id=1234
secret={SECRET}
Value type
String. Mandatory
Description
Provided validation code
Example
secret=34755f16b4cc907cccf268ea19056641
subid={SUBID}
Value type
String. Mandatory
Description
Unique source ID
Example
subid=sub_id_1
ip={USER_IP}
Value type
String. Mandatory
Description
Valid public IPv4 of the user
Example
ip=82.1.24.250
tokenid={USER_ID}
Value type
String. Mandatory
Description
Unique user id generated by the partner
Example
tokenid=4112c824-aa21-4ee3-bc85-26b4e60fd976
ua={USER_AGENT}
Value type
String. Mandatory
Description
The url encoded User Agent string of the user
Example
ua=Mozilla%2F5.0%20%28Linux%3B%20Android%2010%3B%20SM-A217M%29%20AppleWebKit%2F537.36%20%28KHTML%2C%20like%20-Gecko%29%20Chrome%2F88.0.4324.93%20Mobile%20Safari%2F537.36
lang={USER_LANG}
Value type
String. Mandatory
Description
Standard ISO2 user language code. Default is set to 'en'
Example
lang=en
days={USER_DAYS}
Value type
Integer. Mandatory
Description
Days count since the user subscription date, starting on 0
Example
days=7
click_id={CLICK_ID}
Value type
String. Optional
Description
Unique ID for this bid. If not provided will be generated automatically.
Example
click_id=123e4567-e89b-12d3-a456-426655440000
ch-ua={SEC-CH-UA}
Value type
String. Optional
Description
Encoded user agent header hint sec-ch-ua
Example
ch-ua=%22Google%20Chrome%22%3Bv%3D%22123%22%2C%20%22Not%3AA-Brand%22%3Bv%3D%228%22%2C%20%22Chromium%22%3Bv%3D%22123%22
ch-uafull={SEC-CH-UA-FULL-VERSION}
Value type
String. Optional
Description
User agent header hint sec-ch-ua-full-version
Example
ch-uafull=123.0.6312.106
ch-mobile={SEC-CH-UA-MOBILE}
Value type
String. Optional
Description
Encoded user agent header hint sec-ch-ua-mobile
Example
ch-mobile=%3F0
ch-model={SEC-CH-UA-MODEL}
Value type
String. Optional
Description
Encoded user agent header hint sec-ch-ua-model
Example
ch-model=SM-G955U
ch-platform={SEC-CH-UA-PLATFORM}
Value type
String. Optional
Description
User agent header hint sec-ch-ua-platform
Example
ch-platform=Android
ch-platformv={SEC-CH-UA-PLATFORM-VERSION}
Value type
String. Optional
Description
User agent header hint sec-ch-ua-platform-version
Example
ch-platformv=8.0.0
multiple={MULTIPLE_CAMPAIGNS}
Value type
Integer, 1 | 0. Optional
Description
Indicates whether output should return a single campaign (0) or multiple campaigns (1). Default 0
Example
multiple=1

CONTENT RESPONSE

HTTP 200 OK

Response outputs a JSON formatted string contanining campaign bid objects.

If 'multiple' parameter has been passed with value 1, output will contain a list of multiple campaigns objects. Otherwise a single campaign object will be returned.

Ask your Hullcode integration manager for a suitable url to get a valid request/response example.

SINGLE OBJECT

[{
"content_id":{CONTENT_ID},
"title":{TITLE},
"description":{DESCRIPTION},
"image":{IMAGE_URL},
"icon":{ICON_URL},
"click_url":{CLICK_URL},
"cpc":{CPC_BID}
}]

MULTIPLE OBJECT

[{
"content_id":{CONTENT_ID},
"title":{TITLE},
"description":{DESCRIPTION},
"image":{IMAGE_URL},
"icon":{ICON_URL},
"click_url":{CLICK_URL},
"cpc":{CPC_BID}
},...,{
"content_id":{CONTENT_ID},
"title":{TITLE},
"description":{DESCRIPTION},
"image":{IMAGE_URL},
"icon":{ICON_URL},
"click_url":{CLICK_URL},
"cpc":{CPC_BID}
}]

PARAMETERS SPECIFICATION

"content_id":{CONTENT_ID}
Value type
String
Description
Provided content id. Hexadecimal value
Example
"content_id":"12af3"
"title":{TITLE}
Value type
String
Description
Webpush title
Example
"title":"Moto electrica recorre 400km"
"description":{DESCRIPTION}
Value type
String
Description
Webpush body content text
Example
"description":"Esta moto se carga en solo 15 minutos y promete 400 Km de autonomía"
"image":{IMAGE_URL}
Value type
String
Description
Webpush body content image. Not always provided
Example
"image":"https://hullcode.com/web-monetization.jpg"
"icon":{ICON_URL}
Value type
String
Description
Webpush title icon
Example
"icon":"https://example.com:7043/icon.png?id=cGFy...cyMQ&hash=38138808&click_id=7474...070"
"click_id":{CLICK_ID}
Value type
String
Description
Unique ID for the current webpush bid click
Example
"click_id":"7474a349202b759ee28070"
"click_url":{CLICK_URL}
Value type
String
Description
Webpush click destination content url
Example
"click_url":"https://example.com:7043/click?id=cG...Q3&hash=199499312&click_id=747...70"
"cpc":{CPC_BID}
Value type
Double
Description
CPC bid for the current content
Example
"cpc":0.0254

REQUEST ERROR

HTTP 400 Bad Request

  • Partner identification error, if the response content contains one of the following text: 'Not allowed', 'Partner access error'. Then should verify your partner id and verification code.
  • Wrong parameters might have been provided. Verify parameters names and values codification.

    • NO CONTENT RESPONSE

    HTTP 204 No Content

  • There is no suitable content for the sent values.
  • On high response ratio verify parameters names and values codification.