How to Use URL Query Strings

A URL query string is a data delivery method that provides input data at the end of the URL. E.g.,{mapHashId}?{parameter}={value}

You can deliver data to a ZEP Space or ZEP Script using a URL query strings.

URL Query String Parameters Available in ZEP

1. name

When users who are not signed in enter a Space, you can set their nickname as the value passed as the name parameter.

  • Example:{mapHashId}?name=A

⚠️ Make sure to deactivate nickname settings pop-up for guests!

2. customData

You can pass data to ZEP Script player objects. You can create a whitelist function, such as identifying users by passing user identification information such as SSO token information to ZEP Script.

Example 1 Receive user information with customData and apply it. (Normal app, sidebar app recommended)

⚡ URL used for example{mapHashId}?customData={"name":"customUser", "moveSpeed":150, "title":"customTitle"}

App.onJoinPlayer.Add(function (player) {
  // Checks if there is customData passed
	if (player.customData) {
		// Converts customData to object and uses
		let playerCustomData = JSON.parse(player.customData);
		if (playerCustomData.hasOwnProperty("name")) { = playerCustomData["name"];
		if (playerCustomData.hasOwnProperty("moveSpeed")) {
			player.moveSpeed = playerCustomData["moveSpeed"];
		if (playerCustomData.hasOwnProperty("title")) {
			player.title = playerCustomData["title"];
		App.sayToAll("customData applied");
  // Displays message if there is no customData passed
  else {
		App.sayToAll("customData not delivered.");

Example 2

Create a simple token-based whitelist function. (Normal app, sidebar app recommended)

✅ A token with base64 encryption in the browser developer tools (F12) has been created as follows:

⚡ URL used for example{mapHashId}?customData=JTdCJTIydG9rZW4lMjIlM0ElMjIlRUMlOUMlQTAlRUMlQTAlODAxJTJGd2hpdGVMaXN0JTIyJTdE

App.onJoinPlayer.Add(function (player) {
	player.tag = {};
	if (player.customData) {
		let token = player.customData;
		// Sends token to widget to decrypt
		player.tag.widget = player.showWidget("main.html", "topleft", 1, 1);
			type: "decode",
			token: token,
		player.tag.widget.onMessage.Add(function (player, data) {
			if (data.type == "decode") {
				let decodedToken = data.decodedToken;
				// Receives the decrypted code and converts it to an object
				let playerData = JSON.parse(decodedToken);

				let playerName = playerData["token"].split("/")[0];
				let isTrusted = playerData["token"].split("/")[1];

				if (isTrusted == "whiteList") { = playerName;
					player.title = "verified user";
				player.tag.widget = null;
	} else {
		App.sayToAll("customData not delivered.");
// Script used in widget
window.addEventListener("message", function (e) {
  if ( == "decode") {
		// Decrypt the base64 token
    decodedToken = decodeURIComponent(atob(;
      type: "decode",
      decodedToken: decodedToken
    }, "*")

Last updated