Start Session

The startSession endpoint is called when a new user session begins on the client application. This call can be made before an engagement

begins.

https://{tagserver.domain}/tagserver/v1/dataCollection/startSession

URI	startSession
HTTP Method	POST
Formats	JSON

Parameters

Parameter Name	Description	Required	Data Constraints
applicationID	Id associated with the application, if applicable	No	String
applicationVersion	Version number associated with the application, if applicable.	No	String
attributes	List of any modifiable name/value attributes that will be associated with this customer, engagement or session.	No	N/A
attributes:action	Action to be performed on this attribute.	No	Must be one of : append set remove Default value is append.
attributes:attributeType	Type of attribute being set or modified.	Yes	Must be one of: sessionAttribute visitorAttribute
attributes:externalCustomerID	Can only be used for visitor attributes. If this visitor attribute is being used as a unique identifier for the user, this field value should be yes.	No	Must be either yes or no. Default is no.
attributes:name	Name of this attribute.	Yes	String
attributes:value	Value of this attribute. Can be multi-valued.	Yes	String
browserType	Browser type, if applicable.	No	String
browserVersion	Browser version, if applicable.	No	String
customVariables	Stores information for targeting.	No	N/A
customVariables:action	Action to be performed on this custom variable.	No	Must be one of: append set remove Default value is append.
customVariables:name	Name of this custom variable.	Yes	String
customVariables:persistence	Recommended lifespan persistence for the session.	No	Must be either volatile or persistent. Default value is persistent.
customVariables:value	Value of this custom variable. Can be multivalued.	Yes	String
deviceType	Type of device.	No	String
engagementID	Id of the engagement. This value is provided by the Nuance platform. Used only for engagement attributes.	No, but required for engagementAttribut es	String, possible values are: [az], [A-Z], [0-9], [-], [_]
OS	Operating system name.	No	String
sessionID	Id of current session.	No	String
siteID	Id of the site. This value is provided by the Nuance platform It is a static value for the client application.	Yes	Integer
tcCustomerID	The customerID is provided by the Nuance CEAPI when the /engagement endpoint is called.	No	String, possible values are: [az], [A-Z], [0-9], [-], [_]
viewID	Identifier for the current content displayed (or otherwise provided) to the customer	No	String

Response values

Name	Type	Description
tcCustomerID	Integer	If a tcCustomerID was not provided in the request, then a tcCustomerID is generated and returned in the response. and return it in the response.
sessionID	Integer	If a sessionID was not provided in the request, then a sessionID is generated and returned in the response.

JSON Input data example

{
  "tcCustomerID": "12345",
  "siteID": 6789,
  "viewID": "value",
  "applicationID": "myClientApp4.5.2",
  "applicationVersion": "v6.7.8.9",
  "deviceType": "iPad2",
  "OS": "iOS9",
  "browserType": "Safari",
  "attributes": [{
      "name": "device",
      "value": "iPad",
      "attributeType": "sessionAttribute"
    }, {
      "name": "place",
      "value": "LA",
      "attributeType": "visitorAttribute"
    }
  ]
}

JSON schema

{
  "$schema": "http://json-schema.org/schema",
  "type": "object",
  "properties": {
    "tcCustomerID": {
      "type": "string"
    },
    "tcCustomerId": {
      "type": "string"
    },
    "siteID": {
      "type": "integer"
    },
    "sessionID": {
      "type": "string"
    },
    "sessionId": {
      "type": "string"
    },
    "applicationID": {
      "type": "string"
    },
    "applicationVersion": {
      "type": "string"
    },
    "deviceType": {
      "type": "string"
    },
    "OS": {
      "type": "string"
    },
    "browser": {
      "type": "string"
    },
    "businessUnitID": {
      "type": "integer"
    },
    "agentGroupID": {
      "type": "integer"
    },
    "attributes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "attributeType": {
            "type": "string",
            "enum": ["visitorAttribute", "sessionAttribute"]
          },
          "action": {
            "type": "string",
            "enum": ["set", "remove", "append"]
          },
          "externalCustomerID": {
            "type": "string",
            "enum": ["yes", "no"]
          }
        },
        "required": ["name", "value", "attributeType"]
      }
    },
    "customVariables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "action": {
            "type": "string",
            "enum": ["set", "remove", "append"]
          },
          "persistence": {
            "type": "integer"
          }
        },
        "required": ["name", "value"]
      }
    }
  },
  "required": [
    "siteID"
  ]
}

Examples

Request

POST https://{tagserver.domain}/tagserver/v1/dataCollection/startSession

POST body:

{
  "tcCustomerID": "my_Customer-1",
  "siteID": 306,
  "businessUnitID": 22,
  "agentGroupID": 10004091,
  "viewID": "~!@#$%^&*()_+{}|:<>?`-=[];,./     Aa123",
  "applicationID": "my_ClientApp-4",
  "applicationVersion": "my_ClientVers-v3",
  "sessionID": "my_Session-1",
  "engagementID": 1123154123,
  "deviceType": "iPad_2-3",
  "OS": "iOS_9-2",
  "browserType": "Safari_1-4",
  "browserVersion": "1_4",
  "customVariables": [{
      "name": "Cv <>!-',;: kk",
      "value": "Value <>!-',;: 887",
      "action": "set",
      "persistence": 48
    }
  ],
  "attributes": [{
      "name": "visAttr 1",
      "value": "Value11",
      "attributeType": "visitorAttribute",
      "externalCustomerID": "yes",
      "action": "set"
    }, {
      "name": "attr1",
      "value": "Value11",
      "attributeType": "sessionAttribute",
      "action": "remove"
    }
  ]
}

Response

200 OK

Response body:

{
    "tcCustomerId": "my_Customer-1",
    "sessionId": "my_Session-1"
}