Protocols

MyScript Cloud can work with two protocols:

  • HTTP/REST,
  • WebSocket.
A request cannot exceed 800,000 bytes.

HTTP/REST protocol

Each HTTP/REST request implies a new connection that you have to scramble. Creating and scrambling new requests take time, as your recognition parameters as well as input units (Text) or components (Shape, Math, Analyzer, Music) have to be sent each time.

Request example

textInput =
  {
       "textParameter":{
          "language":"en_US",
          "textInputMode":"CURSIVE"
       },
       "inputUnits":[
          {
             "textInputType":"MULTI_LINE_TEXT",
             "components":[
                {
                   "type":"stroke",
                   "x":[
                      438,
                      439,
                      439
                   ],
                   "y":[
                      319.5,
                      313.5,
                      312.5
                   ]
                }
             ]
          }
       ]
    }

Response example

HTTP/1.1 200 OK

{
   "result":{
      "textSegmentResult":{
         "selectedCandidateIdx":0,
         "candidates":[
            {
               "label":"a",
               "normalizedScore":1.0,
               "resemblanceScore":0.9970794,
               "children":[
               ]
            }
         ]
      }
   },
   "instanceId":"9232b0ea-16d5-41fb-93e0-50fe99c0b70a"
}

Sending requests for recognition

The MyScript recognition engine is located on a remote server. When you integrate MyScript Cloud in your solution, access to recognition is granted when an appropriate HTTP request is received by the recognition service, based on our server.

There are different types of recognition available: Text, Shape, Math, Music and Analyzer (Text + Shape), with a different URL for each type. Each request is for a distinct type of input: You cannot mix Shape and Math in the same request for example.

Each HTTP/REST request, written in JSON format:

  • must pass certain parameters that describe the type of recognition you want to perform,
  • may supply the recognition engine with helpful information about the input (for Text recognition),
  • can also ask for certain details to appear in the result,
  • must supply the ink strokes as an XY array,
  • must supply an application key and an HMAC value to authenticate the request (generated on registration to the service).

The request must be made as a simple POST request. Use a JSON format, such as the examples shown via the JSON Examples page.

JSON (JavaScript Object Notation) is a common Internet format that provides a simple method of representing arbitrary data structures. JSON is a text format that is not language-related but uses conventions that are familiar to programmers of C and related languages.

Receiving recognition results

The results of your request are returned from the recognition server. The form taken by the results depends on the type of request:

Request  Feedback
Text  character strings
Shape  a type of shape and its spatial characteristics
Math  a LaTeX or MathML string
Music  a result in MusicXML or ScoreTREE strings
Analyzer  both character strings and a type of shape and its spatial characteristics

Your application has to take in charge the visual rendering of the results.

Results begin with a standard HTTP status code.

Here are the most common errors that you will see returned:

Error  Explanation
200  Your request was successful.
4xx  There is a problem in your request.
5xx  There is a server problem.

See the list of common errors for this API.

The level of detail of your result depends on the level of detail requested in the POST request. For Text recognition, you can specify several parameters to ask for the result to have a certain structure and contain certain information. For Shape, there is a default result. For Math and Music, you can choose your output format.

Authenticating the request

The application key and HMAC value have to be added to each request. Once you have carried out the URL encoding on the request, it should use the format described in the below table.

See the Registration keys and values section to see how to obtain the HMAC value.
Recognition type  Request
Text applicationKey=Your_applicationKey&hmac=Your_hmacValue&textInput=InputText_urlEncoded
Shape applicationKey=Your_applicationKey&hmac=Your_hmacValue&shapeInput=InputShape_urlEncoded
Math applicationKey=Your_applicationKey&hmac=Your_hmacValue&mathInput=InputMath_urlEncoded
Analyzer applicationKey=Your_applicationKey&hmac=Your_hmacValue&analyzerInput=InputAnalyzer_urlEncoded
Music applicationKey=Your_applicationKey&hmac=Your_hmacValue&musicInput=InputMusic_urlEncoded

This proves that you are an authentic user. Depending on your invoicing method (volume, number of users or container), you may need to specify some extra parameters.

  • If you are invoiced by a count of containers: containerType=myContainerType1&containerId=myContainerId1

  • If you are invoiced by a count of users: userId=myUserId1

  • If you are invoiced on volume of traffic, you do not need to use these parameters.

MyScript also provides management of referer/IP filters. Make sure that your application header includes the reference supplied to you on registration or access will be denied.

The application key is potentially visible to all your users. We strongly recommend that you restrict it to a specific domain, to avoid illegitimate use of your application key.

WebSocket Protocol

The WebSocket protocol is a connected handwriting recognition mode, allowing you to create a unique scrambled connection, where requests are continuously sent and received. This protocol can be time-saving but implies to be supported by your browser, as well as a high-speed and very stable Web connection.

A server timeout is to be expected after 90 seconds of inactivity. In that case, you will lose existing strokes and need to refresh the page.

The WebSocket protocol is only possible for Text and Math requests.

Even if you are using the WebSocket protocol, lists of resources, languages, etc. can only be obtained via the HTTP/REST protocol (see below).

Initialization

Step 1: Request the server to open a socket, by sending your application key.

	{  
	"type":"applicationKey",  
	"applicationKey":"fd364014-2040-a49c-c9ab-f45d5303afc3"  
	}  

Step 2: The server sends you an HMAC challenge, i.e. a random character string to check that you are a valid user.

	{
	"type":"hmacChallenge",  
	"challenge":"6401fd34-4200-49ac-ac9b-5303f45dafc3"  
	} 

Step 3: Send back the computed HMAC value to the server.

See the Registration keys and values section to see how to obtain the HMAC value.
{
	"type":"hmac",
	"applicationKey":"fd364014-2040-a49c-c9ab-f45d5303afc3",
	"challenge":"6401fd34-4200-49ac-ac9b-5303f45dafc3",
	"hmac":"764ef6387ee146d2fd384efdc24255e402274a158a379ab42eb420c4fa5ebf4740d
	07d8ee4da62ce58c8cb7fe7208ad6c5b43d75e73457ba9ffd81f02d893549"
}

Step 4: The server sends you an init message to confirm the socket is now secure, open and available to requests.

	{
	"type":"init",
	"result":"success"
	}

Recognition

Step 1: To launch the recognition process, you have to send a start message with your recognition parameters as well as input units (Text) or components (Math).

	{
	"type":"start",
	"parameters":{
      "resultTypes":[
         "LATEX",
         "MATHML",
         "SYMBOLTREE"
      ],
      "isColumnar":false,
      "userResources":[

      ]
	},
   "components":[
      {
         "type":"stroke",
         "x":[
            128,
            129,
            130,
            133
         ],
         "y":[
            364,
            362,
            359,
            356
         ],
         "t":[

			]
		}
	]
}

Step 2: The following messages have to be sent with the continue type. No need to add your parameters, as they have already been sent in the first request.

	{
   "type":"continue",
   "components":[
      {
         "type":"stroke",
         "x":[
            377,
            377,
            377,
            376
         ],
         "y":[
            420,
            423,
            427,
            432
         ],
         "t":[

         ]
      }
   ],
   "instanceId":"4c702b91-cca6-4598-9131-60b1fed589eb"
}

Step 3: Responses are continuously received in real time from the server.

	{
   "type":"mathResult",
   "result":{
      "results":[
         {
            "type":"LATEX",
            "value":"r"
         },
         {
            "type":"SYMBOLTREE",
            "root":{
               "type":"nonTerminalNode",
               "name":"expression",
               "selectedCandidate":0,
               "candidates":[
                  {
                     "type":"rule",
                     "name":"identity",
                     "children":[
                        {
                           "type":"nonTerminalNode",
                           "name":"term",
                           "selectedCandidate":0,
                           "candidates":[
                              {
                                 "type":"rule",
                                 "name":"identity",
                                 "children":[
                                    {
                                       "type":"nonTerminalNode",
                                       "name":"exponentiable",
                                       "selectedCandidate":0,
                                       "candidates":[
                                          {
                                             "type":"rule",
                                             "name":"identity",
                                             "children":[
                                                {
                                                   "type":"terminalNode",
                                                   "name":"symbol1",
                                                   "selectedCandidate":0,
                                                   "candidates":[
                                                      {
                                                         "label":"r",
                                                         "normalizedRecognitionScore":0.3382807
                                                      },
                                                      {
                                                         "label":"2",
                                                         "normalizedRecognitionScore":0.20734294
                                                      },
                                                      {
                                                         "label":"1",
                                                         "normalizedRecognitionScore":0.14948943
                                                      }
                                                   ],
                                                   "inkRanges":[
                                                      {
                                                         "component":0,
                                                         "firstItem":0.0,
                                                         "lastItem":47.0
                                                      }
                                                   ]
                                                }
                                             ]
                                          }
                                       ]
                                    }
                                 ]
                              }
                           ]
                        }
                     ]
                  }
               ]
            }
         },
         {
            "type":"MATHML",
            "value":"<math xmlns=\"http://www.w3.org/1998/Math/MathML\">\n 
			<mstyle displaystyle=\"true\">\n    <mi> r </mi>\n  </mstyle>\n</math>"
         }
      ],
      "scratchOutResults":[

      ]
   },
   "instanceId":"4c702b91-cca6-4598-9131-60b1fed589eb"
}

Step 4: To reset the recognition process, send a reset message.

	{
	"type":"reset"
	}