NFT Metadata Standards

이 페이지에서는 Klip에서 사용하는 NFT 메타데이터 속성의 표준을 설명합니다. 이 표준에 정의되지 않은 속성과 형식의 경우 Klip 내에서 정상적으로 노출되지 않을 수 있으니 참고 바랍니다.

메타데이터 속성

Klip에서 지원하는 속성값의 이름과 설명은 다음과 같습니다. OpenSea에서 사용하는 속성값과 일부 명칭 차이가 있으니 유의 바랍니다.

이름 타입 설명

이름	타입	설명
name*	string	NFT 이름입니다.
description*	string	NFT에 관한 설명입니다.
image*	string	NFT에 사용할 이미지 URL 주소입니다. 이미지 파일 형식이 아니거나 경로에 확장자가 포함되지 않는 경우 정상적으로 표시되지 않을 수 있습니다.
animation_url	string	NFT에 사용할 동영상 URL 주소입니다. 지원하는 파일 확장자는 .mp4입니다. H.264 코덱이 아니거나 해상도가 3840x2160을 넘는 경우 재생되지 않을 수 있습니다.
background_color	string	NFT 이미지 배경에 사용할 RGB 색상 코드입니다. # 다음에 16진수 6자리 문자열로 표시합니다.
sendable	boolean	TRUE이면 해당 NFT를 Klip에서 다른 사람에게 전송할 수 있습니다. 지정되지 않은 경우 기본값은 TRUE입니다.
group_name	string	NFT를 그룹핑할 때 사용하는 그룹 이름입니다.
group_icon	string	NFT를 그룹핑할 때 그룹 아이콘으로 사용할 이미지 URL 주소입니다.
hashtags	array	해시태그들이 담긴 `string` 배열입니다. 해시태그를 달면 Klip 내에서 NFT를 검색하는데 활용됩니다.
layout	string	NFT 이미지를 보여주는 방식입니다. 정사각형 이미지는 `general`, 가로가 더 긴 이미지는 `horizontal`, 세로가 긴 이미지는 `vertical`로 설정할 수 있습니다. 지정되지 않은 경우 기본값은 `general`입니다.
external_link	string	Klip 외부로 연결되는 URL 주소입니다. 지정하면 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (최대 길이: 255)
external_url	string	Klip 외부로 연결되는 URL 주소입니다. 지정하면 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (최대 길이: 255)
custom_links	array	Klip 외부로 연결되는 URL 주소들이 담긴 `object` 배열 입니다. `display_name`에 노출할 버튼 레이블, `value`에 연결할 URL 주소를 쌍을 이뤄 지정합니다. Klip의 NFT 상세 화면에서 외부로 연결되는 링크가 버튼 형태로 제공됩니다. (배열의 최대 크기: 10개, 각 링크의 최대 길이: 255)
qr_code	string	QR Code가 그려진 이미지 URL 주소입니다. (최대 길이: 255)
bar_code	string	Bar Code가 그려진 이미지 URL 주소입니다. (최대 길이: 255)
attributes	array	NFT의 속성값들이 담긴 `object` 배열입니다. `trait_type`으로 노출할 속성명, `value`로 속성값을 쌍을 이뤄 지정합니다. 또한 옵셔널로 `max_value`를 함께 지정하여 속성값의 최대값을 표현할 수 있습니다. 이 경우 `value`의 값은 `max_value`의 값을 초과해서는 안 됩니다.
status_url	string	NFT의 상태 정보를 담고 있는 외부 URL 주소입니다. 해당 URL에서는 JSON 값을 반환해야하고, 필수적으로 bool type의 `valid` 필드와 선택적으로 array type의 `attributes` 필드를 설정할 수 있습니다.

name*

string

NFT 이름입니다.

description*

string

NFT에 관한 설명입니다.

image*

string

NFT에 사용할 이미지 URL 주소입니다. 이미지 파일 형식이 아니거나 경로에 확장자가 포함되지 않는 경우 정상적으로 표시되지 않을 수 있습니다.

animation_url

string

NFT에 사용할 동영상 URL 주소입니다. 지원하는 파일 확장자는 .mp4입니다. H.264 코덱이 아니거나 해상도가 3840x2160을 넘는 경우 재생되지 않을 수 있습니다.

background_color

string

NFT 이미지 배경에 사용할 RGB 색상 코드입니다. # 다음에 16진수 6자리 문자열로 표시합니다.

sendable

boolean

TRUE이면 해당 NFT를 Klip에서 다른 사람에게 전송할 수 있습니다. 지정되지 않은 경우 기본값은 TRUE입니다.

group_name

string

NFT를 그룹핑할 때 사용하는 그룹 이름입니다.

group_icon

string

NFT를 그룹핑할 때 그룹 아이콘으로 사용할 이미지 URL 주소입니다.

hashtags

array

해시태그들이 담긴 string 배열입니다. 해시태그를 달면 Klip 내에서 NFT를 검색하는데 활용됩니다.

layout

string

NFT 이미지를 보여주는 방식입니다. 정사각형 이미지는 general, 가로가 더 긴 이미지는 horizontal, 세로가 긴 이미지는 vertical로 설정할 수 있습니다. 지정되지 않은 경우 기본값은 general입니다.

external_link

string

Klip 외부로 연결되는 URL 주소입니다. 지정하면 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (최대 길이: 255)

external_url

string

Klip 외부로 연결되는 URL 주소입니다. 지정하면 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (최대 길이: 255)

custom_links

array

Klip 외부로 연결되는 URL 주소들이 담긴 object 배열 입니다. display_name에 노출할 버튼 레이블, value에 연결할 URL 주소를 쌍을 이뤄 지정합니다. Klip의 NFT 상세 화면에서 외부로 연결되는 링크가 버튼 형태로 제공됩니다. (배열의 최대 크기: 10개, 각 링크의 최대 길이: 255)

qr_code

string

QR Code가 그려진 이미지 URL 주소입니다. (최대 길이: 255)

bar_code

string

Bar Code가 그려진 이미지 URL 주소입니다. (최대 길이: 255)

attributes

array

NFT의 속성값들이 담긴 object 배열입니다. trait_type으로 노출할 속성명, value로 속성값을 쌍을 이뤄 지정합니다. 또한 옵셔널로 max_value를 함께 지정하여 속성값의 최대값을 표현할 수 있습니다. 이 경우 value의 값은 max_value의 값을 초과해서는 안 됩니다.

status_url

string

NFT의 상태 정보를 담고 있는 외부 URL 주소입니다. 해당 URL에서는 JSON 값을 반환해야하고, 필수적으로 bool type의 valid 필드와 선택적으로 array type의 attributes 필드를 설정할 수 있습니다.

token uri에 data:application/json 으로 시작하는 data uri를 지정하는 경우, 일부 화면에서 정상적으로 처리되지 않을 가능성이 있고 1024자 이상은 지원되지 않습니다. 가능하면 http 또는 https URL을 사용하는 것을 권해드립니다.

권장 이미지 및 영상 규격

Klip에 노출되는 NFT 이미지와 영상은 각각 권장 규격과 파일 형식이 존재합니다. 아래 기준을 따르지 않는 경우 NFT 이미지 또는 영상이 정상적으로 표시/재생되지 않을 수 있습니다.

이미지 규격
- 최소 크기: 1024px x 1024px 이상
- 최대 크기: 23170px x 23170px 이하
- 용량: 5MB 이하
- 확장자: JPG, JPEG, GIF, PNG 등 이미지 파일 확장자 (동영상 형식 미지원)
- 해상도: 72dpi 이상
영상 규격
- 최대 크기: 가로 3840px, 세로 2160px 이하
- 용량: 50MB 이하
- 확장자: MP4
- 동영상 코덱: H.264
- 오디오 코덱: AAC
- 레터박스는 영상에 포함하지 않는 것을 권장

구조와 예시

Klip에서 지원하는 속성에 맞춰 작성된 메타데이터의 예시는 아래와 같습니다.

{
    "name": "Magic Sword",
    "description": "You can summon a demonic sword with a magic attribute.",
    "image": "https://media.klipwallet.com/card_asset/163632/c6525c6e-060c-426f-9275-0dabadb0ba97.png",
    "background_color" : "#ffffff",
    "sendable": true,
    "group_name": "Weapon",
    "group_icon": "https://media.klipwallet.com/temp_eventcard/bomb_klip.jpg",
    "hashtags": ["Game","GroundX","Magic"],
    "layout": "general",
    "external_link": "https://gxmagicgame.com",
    "custom_links": [
        {
            "display_name": "Klip Homepage",
            "value": "https://klipwallet.com/"           
        },
        {
            "display_name": "GroundX Homepage",
            "value": "https://www.groundx.xyz/"
        }
    ],
    "attributes" : [
        {
            "trait_type": "Sword",
            "value" : "Iron Short Sword"
        }, 
        {
            "trait_type": "Magic Type",
            "value": "Fire"
        },
        {
            "trait_type": "Sword Level",
            "value": "5",
            "max_value": "10"
        },
        {
            "trait_type": "Magic Level",
            "value": 2,
            "max_value": 15
        }
    ],
    "status_url" : "https://fakeapi.gx.com/itemstatus?item_id=923874829"
}

여기에서 status_url에 지정된 URL 주소를 통한 응답값 예시는 아래와 같습니다.

{
    "valid": true,
    "attributes": [
        {
            "trait_type": "VIP Membership",
            "value": "Applicable"
        },
        {
            "trait_type": "Expiration Date",
            "value": "2023-12-31"
        }
    ]
}

위의 예시 메타데이터로 발행한 NFT가 Klip에서 어떻게 보이는지 살펴보겠습니다.

먼저 메타데이터에 포함된 image 파일이 NFT 대표 이미지로 나타나고, 그 아래로 name과 description이 표시됩니다. animation_url을 추가하여 동영상이 있는 경우에도 image는 필수 값으로, 여기에 지정된 이미지가 대표 이미지로 표시되고 동영상은 대표 이미지를 클릭해 확인할 수 있습니다. name 아래에 group_icon과 group_name 정보가 표시됩니다. 그룹이 지정되면 콜렉션 내의 NFT 목록에서 상단에 필터 메뉴가 표시되어 빠른 분류 및 검색이 가능합니다. description 아래에 hashtags를 통해 지정한 해시태그 값들이 #가 자동으로 붙어 표시됩니다.

status_url로 동적 정보가 지정된 경우, 그 하단에 상태값과 속성을 실시간으로 가져와 NFT 정보에 보여줍니다.

그 하단으로 attributes를 통해 지정한 세부 속성값이 trait_type - value 쌍으로(max_value가 함께 지정된 경우 최대값이 함께 표시), external_link를 통해 지정한 URL이 클릭 가능한 관련 링크로, custom_links를 통해 지정한 레이블명(display_name)과 URL(value)값이 각각 버튼 링크로 표시됩니다. 외부 링크는 클릭 시, 외부 브라우저를 통해 앱 전환되어 열리게 됩니다. 아울러 본 NFT는 sendable이 true로 지정되어있기 때문에 "보내기" 버튼이 화면 오른쪽 상단의 메뉴 아이콘 버튼을 통해 제공됩니다. 그 이하로 표시되는 내용들은 NFT의 수신 내역과 콜렉션에 대한 정보들로, 메타데이터와 직접적으로 관련 있는 내용은 아닙니다.

이렇게 외부에서 Klip의 표준에 맞춰 구성된 메타데이터가 Klip UI 상 어떻게 표시되는지 알아보았습니다. 본 스크린샷은 환경에 따라, 또는 추후 Klip UI 개선/변경에 따라 다소 차이가 발생할 수 있습니다.

이 문서 혹은 Klip에 관한 문의는 개발자 포럼을 방문해 도움을 받으십시오.

PreviousDesign Guidelines NextChange Log

Last updated 3 months ago