Page tree
Skip to end of metadata
Go to start of metadata
Target release2.1.8
Theme
Document statusREADY
Document ownerAnton Sotniychuk
Designer
DevelopersVladimir Samoylov
QAOleg Agafonov

 

Functions

SDK


All "timestamp" in parameters have to present Server time measured as Unix timestamps in milliseconds and have (long) type.

See more here.

CustomerRegistrationPost

DescriptionCustomer's device registration
Call conditionsOnetime call at first start
HTTP MethodPOST
Parameters
(GUID) DeveloperID  
(string) MarketAppID 
(string) DeviceName 

Parameters

example

{
	"DeveloperID":"A394FB10-8778-488A-B7C2-86858A77BED2",
    "MarketAppID":"Parent",
    "DeviceName":"G3SMNTA24"
}
Response

(GUID) SDKInstanceID

(long) ServerTimestamp

CustomerDisableAtHisRequestPost

Description

Customer device registration freezes by her/his own request ("I don't like to receive something like that anymore")

Receives extra options to illuminate disabling by mistake

Call conditions-
HTTP MethodPOST
Parameters
(GUID) DeveloperID  
(string) MarketAppID 
(string) DeviceName 
(GUID) SDKInstanceID 

Parameters

example

{
  "SDKInstanceID" : "CA09D1C3-C4C7-463A-9FDA-104F58D82986",
  "DeveloperID":"A394AB10-8778-488A-B7C2-86858A77BED2",
  "MarketAppID":"Parent"
}
ResponseNO

CustomerLocationPost

DescriptionSends customer location GEO info sending to check entrance to radius
Call conditions-
HTTP MethodPOST
Parameters
(GUID) SDKInstanceID

 

 

GeoPointList
(long) GEOTimestampGEO's time provided by GEOmodule (may be cached).
Unix timestamps in milliseconds 
(long) ClientTimestampTime of request to GEOmodule.
Unix timestamps in milliseconds. 
(double) Latitude 
(double) Longitude 
(float) Accuracy 
(int) ProviderTypeIDNULL = unknown, 1 = GPS (not used now), 2 = Wi-Fi/Cellular network
(float) Speed 
(float) Bearing 
(double) Altitude  
(string) SpecialTagIdUndocumented tag for promo capabilities

Parameters

example

{
 "SDKInstanceID":"6F8FBK99-C8E8-4722-A5DB-DD5BCFF36BF2",
 "SpecialTagId":"",
 "GeoPointList": [
   {
     "Latitude": "59.868519",
     "Longitude": "30.269643",
     "Altitude": 0,
     "Accuracy": 39.187,
     "GEOTimestamp": "1443127349012",
     "ClientTimestamp": "1443127357016"
   }
 ]
}
Response

ServerToClient message list (opt.)

(long) ServerTimestamp

FenceListGet 

DescriptionReturns actual radius list for current region
Call conditionsFenceListProposalGet message was received from server
HTTP MethodGET
Parameters

(GUID) SDKInstanceID 

Response
FenceList
(int) FenceID 
(double) GEOLatitude 
(double) GEOLongitude 
ServerToClient message list (opt.) 
(long) ServerTimestamp 

Response

example

{
  "FenceList":[
               {"FenceID":14,
                "GEOLatitude":59.868495,
                "GEOLongitude":30.269313},
               {"FenceID":16,
                "GEOLatitude":60.0390459681448,
                "GEOLongitude":30.263065}
              ],
  "MessageList":[],"ServerTimestamp":1458654982111
}

HotGet

DescriptionGets information about advert offer
Call conditionsHotProposalGet message was received from server
HTTP MethodGET
Parameters

(GUID) SDKInstanceID 

Response
Hot
(int) ID 
PointGEO (longitude & latitude only)

 

(double) GEOLatitude 
(double) GEOLongitude 
(int) Radius
 
 
(string) Text 
not in use now
(int) Code
 
(double) Bonus
 
(int) Duration
 
(long) FinalTimeUnix timestamps in milliseconds.
(int) Floor
 
(string) PublicName
 
(string) Address
 
(URL) Logotype 
(URL) Photo 
(string) DirectionOutside
 
(string) DirectionInside
 
(string) DirectionLost
 
(int) DOSPayoffAmount
 
(int) FriendCount

 
ServerToClient message list (opt.) 
(long) ServerTimestamp 

Response

example

{
	"Hot":
		{"ID":(int),
         "Point":{"GEOLatitude":(double),"GEOLongitude":(double)},
         "Radius":(int),
		 "Text":(string),
		 "Code":(int),
		 "Bonus":(double),
         "Duration":(int),
		 "FinalTime":(long WUnix milisec),
		 "Floor":(int),
 		 "PublicName":(string),
         "Address":(string),
		 "Logotype":null,
		 "Photo":null,
		 "DirectionOutside":(string),
		 "DirectionInside":(string),
	     "DirectionLost":(string),
		 "DOSPayoffAmount":(int),
		 "FriendCount":(int)
		},
    "MessageList":[
		{"MsgName":(string),
		 "ExpDateTime":(long WUnix milisec)
		}
     ],"ServerTimestamp":1458654982111
}

SocialNetworkDataPost

DescriptionSends nameless info to server
Call conditionsSocialNetworkDataRequestPost message was received from server or current App was white labeled by techsupport
HTTP MethodPOST
Parameters
(GUID) SDKInstanceID  
CustomerSocialProfile
(byte)Type(1-Device,2-VK; 3-FB) 
(long) InfoTimestampUnix timestamps in milliseconds.
(bit) Gender (0-Female;1-Male)"-1" means NULL
(int) BirthdayYear"-1" means NULL
(byte) BirthdayMonth"-1" means NULL
(byte) BirthdayDay"-1" means NULL
(byte) AgeRangeFrom"-1" means NULL
(byte) AgeRangeTo"-1" means NULL
(string) ResidenceCity 
(string) ResidenceCountry 
(string) HomeTown 
(bit) HighEducation"-1" means NULL
(string) Occupation 
(string) Interests 
(byte) RelationshipStatus(0-single; 1-relations; 2-married; 3-divorced); "-1" means NULL
(string) Languages 

Parameters

example

{"SDKInstanceID":"6F8FB799-C8E8-4722-A5DB-DD5BCFF36BF2",
 "CustomerSocialProfile": 
   {
     "Type": 2,
     "InfoTimestamp": 1443118598012,
     "Gender": 1,
     "BirthdayYear":1992,
     "BirthdayMonth":06,
     "BirthdayDay":15,
     "AgeRangeFrom":10,
     "AgeRangeTo":-1,
     "ResidenceCity":"Санкт-Петербург",
     "ResidenceCountry":"Россия",
     "HomeTown": "Корсаков",
     "HighEducation": 1,
     "Occupation":"исследователь, CEO",
     "Interests":"история, флот",
     "RelationshipStatus":2,
     "Languages":"Русский, English"
   }
 ,
"AdditionalInfoList": [
  
]
}
Response(long) ServerTimestamp

EventPost

DescriptionSends customer events to server
Call conditions-
HTTP MethodPOST
Parameters
(GUID) SDKInstanceID  
EventList
(byte) TypeCustomerEventType
(long) EventTimestampUnix timestamps in milliseconds.

Parameters

example

{"SDKInstanceID":"6F8FBD99-C8E8-4722-A5DB-DD5BCFF36BG2",
 "EventList": [
   {
     "EventTimestamp": "1448392154770",
     "Type": "3"
   },
   {
     "EventTimestamp": "1448391954770",
     "Type": "8"
   }
 ]
}
Response

ServerToClient message list (opt.)

(long) ServerTimestamp

HotStatusPost

DescriptionSends hot's status to server (as soon as possible after change status)
Call conditionsHotID exists
HTTP MethodPOST

Parameters

(GUID) SDKInstanceID 
HotStatusList
(int) HotID 
(long) ClientTimestampUnix timestamps in milliseconds.

(byte) HotStatus

5Notified
6Viewed
7Used
10Rejected
11NotUsed
12DOS
13NotShowedByCondition
 

Parameters

example

{
 "SDKInstanceID": "6F8FBD99-C8E8-4722-A5DB-XC5BCFF36BF7",
 "HotStatusList": [
   {
     "HotID": "258",
     "ClientTimestamp": "1443127297012",
     "HotStatus": "5"
   },
   {
     "HotID": "258",
     "ClientTimestamp": "1443127299012",
     "HotStatus": "6"
   },
   {
     "HotID": "258",
     "ClientTimestamp": "1443127598014",
     "HotStatus": "10"
   }
 ]
}
Response

ServerToClient message list (if there are messages)

(long) ServerTimestamp

DebugLogPost

DescriptionDebug function
Call conditions-
HTTP MethodPOST
Parameters
(GUID) SDKInstanceID  
(string) Log 

Parameters

example

{
   "SDKInstanceID": "6F8GBD99-C8E8-4722-A5DB-DD5BCFF36BF2",
	"Log": "test log"
}
Response

ServerToClient message list (opt.)

(long) ServerTimestamp

CustomerApplicationsPost 

DescriptionSends customer Applications to server
Call conditionsCustomerApplicationDataRequestPost message was received from server or current App was white labeled by techsupport
HTTP MethodPOST
Parameters
(GUID) SDKInstanceID  
ApplicationList
(string) MarketAppIDmandatory
(long) InstallTimestampUnix timestamps in milliseconds.
(long) ClientTimestampUnix timestamps in milliseconds.
(string) ApplicationNameoptional

Parameters

example

{"SDKInstanceID":"6F8FBD99-C8E8-4722-A5DB-DD5BCFF36BG2",
 "ApplicationList": [
   {
     "MarketAppID":"parent.com",
	 "InstallTimestamp": "1448192154770",
	 "ClientTimestamp": "1448392154770"
   },
   {
     "MarketAppID":"test.ru",
	 "InstallTimestamp": "1445192154770",
	 "ClientTimestamp": "1448392154770",
	 "ApplicationName":"Demo application"
   }
 ]
}
Response

ServerToClient message list (opt.)

(long) ServerTimestamp


AdditionalInfoList (any function optional add-on structure)

Description "AdditionalInfoList"
Stcructure
AdditionalInfoList: [
	{
		"AdditionalInfoType": "ChargingState",
		"Status": "String (POWER_CONNECTED/POWER_DISCONNECTED)",
		"Plug": "String (BATTERY_PLUGGED_USB/BATTERY_PLUGGED_AC)",
		"InfoTimestamp": "Long" (joined with CustomerLocationPost by timestamp! Unix timestamps in milliseconds.)
	},
	{
		"AdditionalInfoType": "ChargingState",
		"Status": "String (POWER_CONNECTED/POWER_DISCONNECTED)",
		"Plug": "String (BATTERY_PLUGGED_USB/BATTERY_PLUGGED_AC)",
		"InfoTimestamp": "Long" (joined with CustomerLocationPost by timestamp! Unix timestamps in milliseconds.)
	}
]


Электроскидка only

QOSPost

DescriptionSends QOS information from customer (any number of times per one Hot)
Call conditionsHotID exists
HTTP MethodPOST
Parameters
(GUID) SDKInstanceID  
(int) HotID 
(string) CustomerComment 
(long) ClientTimestampUnix timestamps in milliseconds.

Parameters

example

{
   "SDKInstanceID": "6FGGBD99-C8E8-4722-A5DB-DD5BCFF36BF2",
   "HotID": "258",
   "CustomerComment": "Грубый персонал",
   "ClientTimestamp": "1443127299012"
}
ResponseNO

DOSPost

DescriptionSends DOS information from customer (only one time per one Hot)
Call conditionsHotID exists and has "Viewed" HotStatusType
HTTP MethodPOST
Parameters
Parameter nameDescription
(GUID) SDKInstanceID  
(int) HotID 
(string) Photo1ID

Cash receipt photo (ID returned
by Image storage server)

SS-154 - Getting issue details... STATUS
(string) Photo2ID

Photo of menu, price list etc. (ID returned
by Image storage server)

  SS-154 - Getting issue details... STATUS

(string) Photo3ID

Photo of counter, cash register, etc. (ID returned
by Image storage server)

  SS-154 - Getting issue details... STATUS

(string) CustomerComment NULLABLE  
(long) ClientTimestampUnix timestamps in milliseconds.

Parameters

example

{
   "SDKInstanceID": "6F8FBF99-C8E8-4722-A5DB-DD5BCFF36BF2",
   "HotID": "27",
   "Photo1ID":"ewrt34555325",
   "Photo2ID":"97456t234",
   "Photo3ID":"64366754",
   "CustomerComment": "Where is my money?!",
   "ClientTimestamp": "1443427299012"
} 
Response

NO

 

ServerToClient Messages

 

Server's functions marked by "Call conditions"  can't be called by client on his own initiative. A special message (proposal or request) must be received by client previously.

Purpose: some kind of security check and DDOS illumination.

Any function except:

 - CustomerRegistrationPost,
- CustomerDisableAtHisRequest,
SocialNetworkDataRequestPost,
- QOSPost,
- DOSPost

may return MessageList response.

 

Message Type

TypeDescription
ProposalServer proposes client app to receive some information by server's GET function call; after ExpDateTime expires, server'll forget about that.
Request 

Server proposes client app to send some information by server's POST function call; after ExpDateTime expires, server'll forget about that.
When client app is presented at white list (ask techsupport) it is possible to send information without message from server. Request functions have no any response.

Command Server gives command to client to do something; server sure that any client application must to do id and does not do any checks.

Messages

TypeNameParameterDescriptionWhen send from server to clientMessageTypeID (internal)
proposalFenceListProposalGetExpDateTimeProposal to client get fence set from server

After registration: at the next time of CustomerLocationPost
Later: once a day

1
proposalHotProposalGetExpDateTimeProposal to client get hot from serverWhen server determines that the user is within range and there is a offer for him2
commandClientQueueResetCommandn/aReset client's commands queue totally to prevent server DDOSDecision on the server3
commandCriticalLogCollectCommandn/aStart critical information collecting during 7 days and sent it to serverDecision on the server5
requestSocialNetworkDataRequestPostExpDateTimeRequest to client send social network profile to server

After registration: at the next time of CustomerLocationPost
Later: once a week

4
requestCustomerApplicationDataRequestPostExpDateTimeRequest to client send device's application list (not marked as system) to serverAfter registration: at the next time of CustomerLocationPost
Later: once a 15 days
6

MessageList response

MessageList:[ 
   {MsgName : "Name1", ExpDateTime:"(long WUnix )"},
   ...
   {MsgName : "NameN", ExpDateTime:"(long WUnix )"}
]

Error Codes

If there are any error on Server side due to execution REST functions server will return HTTP StatusCode = 403 and ErrorList in response

Example
{"ErrorList":[{"ErrorDescription":"Invalid SDKInstanceID (or Customer disabled )"}]}
  • No labels

6 Comments

  1. Grigory PetrovVladimir Samoylov: please check new function CustomerDisableAtHisRequest

  2. For QOSPost - OK.

    For CustomerDisableAtHisRequest:

    • parameter DeviceName may be =  NULL when Customer used CustomerRegistrationPost function. So, if I undersand correctrly, we just check DeviceName value (NULLABLE) with value wich was send due to  CustomerRegistrationPost (or NOT send = NULL).
    • Response - is absent in this function (add to formal documentation) 
    1. По QOSPost замечаний нет.

          2. Зачем CustomerDisableAtHisRequest параметр DeviceName в принципе?

  3. >So, if I undersand correctrly, we just check DeviceName value (NULLABLE) with value wich was send due to  CustomerRegistrationPost (or NOT send = NULL).

    Yes

    > Response - is absent in this function (add to formal documentation) 

    I'm not so sure. In future we could try to receive additional information from client before disabling.

  4. To QOSPost function add parameter (long) ClientTimestamp


    Anton Sotniychuk Need to approving