AJAX object

The AJAX plugin allows web pages to be requested during the running of the game. Its name derives from "Asynchronous JavaScript and XML", a technique familiar to most web developers. The AJAX object is designed for use by web developers already familiar with the technique - this reference will not describe the principles of AJAX itself, only how to use it in Construct 2 with the AJAX object. Using the AJAX object can sometimes involve custom server-side scripting which is beyond the scope of this manual, but requesting simple static resources like text files is straightforward, as well as project files.

How to make a request

The basic usage of the AJAX object consists of:

  1. Use the Request action to load a URL.
  2. A moment later after the request completes, On completed triggers.
  3. The LastData expression can be used to access the content of the response.

The tokenat system expression may be useful to split simple responses. Alternatively, you could load LastData in to the XML plugin to read it as an XML document.

Tags

A different tag can be provided for each request. This is a simple string you set to tell apart different requests. For example, on startup you may request both foo.php with tag "foo" and bar.php with tag "bar". When the first request completes, On "foo" completed triggers; when the second request completes, On "bar" completed triggers. Requests can complete in a different order to the order they were made, so without tags it would be impossible to tell which request was completing.

Making AJAX requests cross-domain or in preview

By default, browsers block AJAX requests across domains. This means, for example, a game on scirra.com can request other pages on scirra.com, but cannot request pages on facebook.com. This is an important security feature of web browsers (it is not specific to Construct 2 or its AJAX object).

Also, when previewing in Construct 2 the game runs on localhost. This counts as a different domain to the rest of the internet, so typically AJAX requests to any web page will fail during preview, unless the server explicitly allows cross-domain requests.

If you want AJAX requests to your server to work from any domain, or in preview, you can configure it to send the following HTTP header:

Access-Control-Allow-Origin: *

This will enable AJAX requests from any domain, but you should still be aware of the possible security implications of this. For more information on cross-domain requests see HTTP access control on MDN.

In NW.js

When exporting desktop applications with NW.js, the AJAX object can also load files from the application folder. Simply use the Request URL action and enter the name of a file in the same directory as the application, e.g. "example.txt". Note if a project file exists with the same name, this will always load the project file instead.

MIME types

AJAX requests for files on your own server requires that your server has the correct MIME types set up.

AJAX conditions

On completed
Triggered when a request with the same tag has completed successfully. The LastData expression contains the response.

On any completed
Triggered when any request has completed successfully. The Tag expression identifies the request, and LastData contains the response.

On error
Triggered when a request with the same tag has failed. This can be for a number of reasons, such as the server being down or the request timing out. (The LastData expression is not set since there is no response.)

On any error
Triggered when any request has failed. The Tag expression identifies the request.

On progress
For long running requests (e.g. downloading a large file), On progress triggers periodically and updates the Progress expression with the state of the request. This is useful for making progress bars for AJAX requests.

AJAX actions

Override MIME type
In some cases you may wish to interpret the server's response with a different MIME type to the one the server indicates. For example a misconfigured server may return a text file with the wrong character set, and you want to force the response to be interpreted as UTF-8. In this case you could override the MIME type as text/plain; charset=utf-8 to avoid garbling the text. This action only applies to the next AJAX request that is made, after which the MIME type will be set back to the default setting of accepting what the server response indicates.

Post to URL
Send a request with data to a URL and retrieve the response. A tag is provided to match it up with the On completed, On progress and On error triggers. Construct 2 does not automatically URL encode the post data - use the URLEncode system expression to ensure the data is in the correct format for posting. Note post data is in the same format as a query string, e.g. "foo=1&bar=2". The method can also be specified: by default it is POST, but for some APIs you may need to change this to PUT, DELETE or another HTTP method.

Request URL
Send a GET request to retrieve the contents of a URL. A tag is provided to match it up with the On completed, On progress and On error triggers.

Request project file
Request the contents of a project file. A tag is provided to match it up with the On completed, On progress and On error triggers.

Set request header
Set a HTTP header on the next AJAX request that is made. After the next AJAX request all the headers set with this action are cleared again, so it only takes effect once.

Set timeout
Set the amount of time a request has to complete in seconds; if the timeout expires without the request completing successfully, it will instead fail and trigger On error. This action only affects subsequent requests, and does not affect any requests that have already started. If the timeout is set to -1 it restores the default browser timeout.

AJAX expressions

LastData
The contents of the last response. This is set in the On completed trigger. If used in a different event, it contains the response of the last completed request. The tokenat system expression may be useful to split simple responses

Progress
Return the progress of the AJAX request in an On progress event. The progress is represented as a number from 0 to 1, e.g. 0.5 for half completed.

Tag
The tag of the AJAX request in a trigger. This is useful to identify requests in On any completed or On any error.

Tags: