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., https://zep.us/play/{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: https://zep.us/play/{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

https://zep.us/play/{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")) {
			player.name = playerCustomData["name"];
		}
		if (playerCustomData.hasOwnProperty("moveSpeed")) {
			player.moveSpeed = playerCustomData["moveSpeed"];
		}
		if (playerCustomData.hasOwnProperty("title")) {
			player.title = playerCustomData["title"];
		}
		App.sayToAll("customData applied");
		player.sendUpdated();
	}
  // Displays message if there is no customData passed
  else {
		App.sayToAll("customData not delivered.");
	}
});

When customData is Successfully Applied

When Failed to Receive customData

Example 2

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

1KB

customData_예제.zip

archive

Open

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

⚡ URL used for example

https://zep.us/play/{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);
		player.tag.widget.sendMessage({
			type: "decode",
			token: token,
		});
		player.tag.widget.onMessage.Add(function (player, data) {
			if (data.type == "decode") {
				let decodedToken = data.decodedToken;
				App.sayToAll(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") {
					player.name = playerName;
					player.title = "verified user";
					player.sendUpdated();
				}
				player.tag.widget.destroy();
				player.tag.widget = null;
			}
		});
	} else {
		App.sayToAll("customData not delivered.");
	}
});

// Script used in widget
window.addEventListener("message", function (e) {
  if (e.data.type == "decode") {
		// Decrypt the base64 token
    decodedToken = decodeURIComponent(atob(e.data.token));
    window.parent.postMessage({
      type: "decode",
      decodedToken: decodedToken
    }, "*")
  }
})

When Successfully Verified with a Token