> For the complete documentation index, see [llms.txt](https://docs-kr.zep.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-kr.zep.us/creator/reference/url.md).
# URL 쿼리스트링 활용하기
URL 쿼리스트링이란 URL의 뒤에 입력 데이터를 함께 제공하는 데이터 전달 방법 입니다. \
**예시)** `https://zep.us/play/{mapHashId}?{파라미터}={값}`
URL 쿼리스트링을 이용해 ZEP 스페이스 또는 ZEP Script로 데이터를 전달 할 수 있습니다.
## ZEP에서 사용 가능한 URL 쿼리스트링 파라미터
### 1. name
비로그인 유저 입장 시 닉네임을 name 파라미터로 전달한 값으로 설정할 수 있습니다.
* 예시: `https://zep.us/play/{mapHashId}?name=학생A`
:warning: 게스트 유저 닉네임 설정 팝업 비활성화 설정을 해주세요!
### 2. customData
ZEP Script player 객체에 데이터를 전달할 수 있습니다. \
SSO 토큰 정보 등의 유저 식별 정보를 ZEP Script로 전달하여 유저를 식별하는 등 화이트리스트 기능을 만드는 데 활용할 수 있습니다.
**예제 1** \
customData로 플레이어 정보를 받아 적용해보기 (노멀앱, 사이드바앱 권장)
⚡예제에서 사용한 URL
`https://zep.us/play/{mapHashId}?customData={"name":"커스텀유저", "moveSpeed":150, "title":"커스텀타이틀"}`
```jsx
App.onJoinPlayer.Add(function (player) {
// 전달받은 customData가 있는지 체크
if (player.customData) {
// customData를 오브젝트로 변환하여 사용
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("커스텀 데이터를 적용했습니다");
player.sendUpdated();
}
// 전달받은 customData가 없다면 메시지 출력
else {
App.sayToAll("커스텀 데이터를 전달받지 못했습니다.");
}
});
```
customData를 전달받지 못한 경우
customData를 전달받아 적용한 경우
**예제 2**
간단한 토큰기반 화이트리스트 기능 만들어보기 (노멀앱, 사이드바앱 권장)
{% file src="/files/fgE7LgU5HV5dQtW2hCcG" %}
✅ 브라우저 개발자 도구(F12)에서 다음과 같이 base64 암호화를 하여 토큰을 만들었습니다.
⚡ 예제에서 사용한 URL
`https://zep.us/play/{mapHashId}?customData=JTdCJTIydG9rZW4lMjIlM0ElMjIlRUMlOUMlQTAlRUMlQTAlODAxJTJGd2hpdGVMaXN0JTIyJTdE`
```jsx
App.onJoinPlayer.Add(function (player) {
player.tag = {};
if (player.customData) {
let token = player.customData;
// 위젯으로 토큰을 보내 복호화하기
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);
// 복호화 된 코드를 받은 후 오브젝트로 변환
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 = "인증된유저";
player.sendUpdated();
}
player.tag.widget.destroy();
player.tag.widget = null;
}
});
} else {
App.sayToAll("커스텀 데이터를 전달받지 못했습니다.");
}
});
```
```powershell
// 위젯에서 사용한 스크립트
window.addEventListener("message", function (e) {
if (e.data.type == "decode") {
// base64 토큰 복호화
decodedToken = decodeURIComponent(atob(e.data.token));
window.parent.postMessage({
type: "decode",
decodedToken: decodedToken
}, "*")
}
})
```
