콘텐츠로 이동

Reference UI Kit

Reference UI Kit은 Hive Axyl SDK 기능을 앱에 구현할 때 참고하는 화면 예시입니다. 로그인 화면이나 계정 관리 화면처럼 사용자에게 직접 보여 주어야 하는 화면을 리소스와 코드로 미리 만들어 제공합니다.

레시피는 Hive Axyl SDK 호출을 목적 단위로 묶어 둔 소스 코드이고, Reference UI Kit은 그 기능을 사용자에게 보여 주는 화면을 미리 만들어 둔 리소스입니다. 둘을 함께 사용하면 화면을 처음부터 설계하지 않고도 계정과 인증 기능을 앱에 구현할 수 있습니다. 레시피가 무엇인지는 유저네임 로그인 활용 가이드를 참조하세요.

제공 화면

Reference UI Kit이 제공하는 화면은 계정과 인증에 필요한 네 가지입니다. 각 화면 가이드에서 화면 예시와 연결할 레시피, 적용할 때 확인할 내용을 살펴보세요.

Reference UI Kit이 맡는 범위

Reference UI Kit은 화면만 담당하므로, 화면 리소스를 가져와 화면을 여는 것만으로는 로그인이 동작하지 않습니다. 앱이 화면 리소스를 레시피나 Hive Axyl SDK 메서드와 연결해야 화면이 동작합니다. 화면 리소스, 레시피, 앱이 맡는 일은 아래와 같습니다.

  • 화면 리소스: 화면 표시, 사용자 입력 수신, 사용자 입력 이벤트 전달, 전달받은 데이터와 상태에 따른 화면 표시 변경
  • 레시피: 앱이 전달한 입력값으로 Hive Axyl SDK를 정해진 순서대로 호출, 처리 결과 반환, Google이나 Apple처럼 사용자를 대신 인증해 주는 외부 인증 제공자의 인증 화면으로 넘어가는 시점 결정
  • 앱: 로그인 수단 목록, 로그인 수단 아이콘, 실패 안내 문구처럼 화면에 표시할 값 전달, 사용자 입력 이벤트에 맞춘 레시피나 Hive Axyl SDK 메서드 호출, 처리 결과에 따른 안내 표시와 화면 이동

화면 리소스는 Hive Axyl SDK를 직접 참조하지 않으므로, 앱의 인증 구조를 바꾸지 않고 화면만 가져와 쓸 수 있습니다. 연결할 레시피와 Hive Axyl SDK 메서드는 화면마다 다릅니다. 화면을 적용하기 전에 각 화면 가이드의 관련 레시피를 먼저 확인하세요. 레시피 호출 순서와 결과별로 앱이 처리할 내용은 레시피 사용 예제를 참조하세요.

로그인 수단 아이콘

화면 리소스에는 저작권 문제로 외부 인증 제공자의 브랜드 아이콘이 들어 있지 않으므로, 앱이 아이콘을 준비해 화면에 전달해야 합니다. 로그인 수단별로 아이콘을 구하는 곳은 아래와 같습니다.

내려받은 아이콘은 형태, 비율, 색을 바꾸지 말고 그대로 사용하세요. 여백만 조정해 전체 크기를 24×24로 맞춘 뒤 전달하세요. 화면은 이 아이콘을 20×20 크기로 표시합니다. 공식 아이콘 대신 비슷하게 그린 아이콘을 쓰면 각 제공자의 브랜드 가이드를 위반할 수 있습니다. 아이콘을 전달하지 않은 로그인 수단은 아이콘 자리에 그림 대신 글자가 들어간 칩으로 표시되므로, 공식 아이콘을 구하기 전에는 이 상태로 두세요.

지원 환경

화면 리소스가 지원하는 환경은 아래와 같습니다. 프로젝트의 Unity 버전이 저장소에 적힌 검증 버전과 맞는지 먼저 확인하세요.

  • 개발 환경: Unity
  • Unity 버전: 저장소에 적힌 검증 버전
  • 기기: PC, 모바일
  • 화면 방향: 세로 화면, 가로 화면

화면 리소스 하나가 위 기기와 화면 방향을 모두 처리하므로, 화면 비율이나 해상도에 따라 리소스를 따로 가져올 필요는 없습니다. 가져올 리소스는 각 화면 가이드의 Unity 적용 안내에서 확인하세요.

화면 리소스 가져오기

화면 리소스는 hive-axyl-reference-ui 저장소에서 가져옵니다. 패키지로 설치해 쓰는 Hive Axyl SDK와 달리 폴더를 프로젝트에 복사해서 쓰므로, 가져온 뒤에는 앱 디자인에 맞게 자유롭게 고쳐 쓸 수 있습니다.

Reference UI Kit은 Hive Axyl SDK와 버전 체계가 다릅니다. Hive Axyl SDK를 업데이트했다고 해서 화면 리소스까지 함께 업데이트할 필요는 없습니다.

TextMesh Pro 필수 리소스

화면 리소스는 Unity의 텍스트 표시 기능인 TextMesh Pro(TMP)를 사용하므로, 프로젝트에 TMP 필수 리소스가 있어야 합니다. 필수 리소스가 없으면 화면 리소스의 텍스트에서 오류가 발생합니다. 새로 만든 프로젝트처럼 필수 리소스를 아직 가져오지 않았다면 Unity 에디터에서 Window > TextMeshPro > Import TMP Essential Resources를 선택해 먼저 가져오세요.

복사할 폴더

저장소의 화면 리소스는 모두 unity/UI-Kit/ 아래에 있습니다. 화면 폴더만 복사하면 공용 위젯, 폰트, 어셈블리 정의 파일이 빠져 화면이 제대로 표시되지 않거나 동작하지 않습니다. 가져올 화면의 폴더와 함께 공용 폴더, 폰트 폴더, 어셈블리 정의 파일도 복사해야 합니다. 각 폴더와 파일의 저장소 경로는 아래와 같습니다.

대상 저장소 경로 들어 있는 것
로그인 화면 폴더 unity/UI-Kit/Login 화면 리소스와 그 화면이 사용하는 공용 위젯 목록
유저네임 로그인 화면 폴더 unity/UI-Kit/UsernameLogin 화면 리소스와 그 화면이 사용하는 공용 위젯 목록
비밀번호 변경 화면 폴더 unity/UI-Kit/PasswordChange 화면 리소스와 그 화면이 사용하는 공용 위젯 목록
계정 관리 화면 폴더 unity/UI-Kit/Account 화면 리소스와 그 화면이 사용하는 공용 위젯 목록
공용 폴더 unity/UI-Kit/Common 닫기 버튼, 실패를 알리는 짧은 메시지인 실패 안내 토스트, 액션 버튼, 입력란처럼 여러 화면이 함께 쓰는 위젯
폰트 폴더 unity/UI-Kit/Fonts 화면의 텍스트 표시에 쓰는 폰트
어셈블리 정의 파일 unity/UI-Kit/UIKit.asmdef 화면 리소스의 스크립트를 하나의 어셈블리로 묶는 설정. 어셈블리는 Unity가 스크립트를 묶어 컴파일하는 단위

unity/UI-Kit/Editor 폴더에는 위젯과 폰트를 다시 만드는 개발용 도구가 들어 있으므로 앱 프로젝트에는 복사하지 않아도 됩니다.

.meta 파일

.meta 파일은 Unity가 프로젝트의 파일마다 만들어 그 파일의 식별자를 기록해 두는 파일입니다. 화면 리소스는 이 식별자로 스크립트, 이미지, 폰트를 참조합니다. .meta 파일이 빠지거나 식별자가 새로 발급되면 참조가 끊어져 화면이 제대로 표시되지 않습니다.

Finder나 파일 탐색기에서 폴더째 복사하면 .meta 파일도 함께 옮겨집니다. 반면 Unity 에디터의 Project 창에 끌어다 놓으면 .meta 파일이 유지되지 않을 수 있습니다. 복사한 화면을 처음 열었을 때 Console 창에 스크립트를 찾지 못했다는 Missing script 경고가 없고 화면이 정상적으로 표시되면 참조가 유지된 것입니다.

복사 방법

가장 안전한 방법은 Finder나 파일 탐색기에서 unity/UI-Kit 폴더를 통째로 앱 프로젝트의 Assets/UI-Kit으로 복사한 뒤, 쓰지 않는 화면 폴더를 지우는 것입니다. 앱에 필요하지 않은 Editor 폴더는 함께 지워도 됩니다. 이때 Common 폴더, Fonts 폴더, UIKit.asmdef 파일은 지우지 말고 남겨 두세요.

Assets/ 폴더 안이라면 다른 위치에 복사해도 되지만, 아래 조건은 지켜야 합니다.

  • 각 폴더 안의 Resources/UIKit/ 폴더와 그 아래 구조를 그대로 유지: 화면 리소스가 위젯과 이미지를 Resources 폴더 기준의 UIKit/... 경로로 읽으므로, 폴더 이름을 바꾸거나 하위 폴더를 옮기면 화면을 열 때 리소스를 찾지 못할 수 있음
  • 화면 폴더, 공용 폴더, 폰트 폴더, UIKit.asmdef 파일을 같은 부모 폴더 아래에 둠: UIKit.asmdef가 같은 폴더 아래의 스크립트를 하나의 어셈블리로 묶으므로, 화면 폴더만 다른 곳으로 옮기면 그 스크립트가 어셈블리에서 빠져 컴파일 오류가 생길 수 있음

어셈블리 참조

앱에 어셈블리 정의 파일이 없으면 앱 스크립트는 Unity의 기본 어셈블리인 Assembly-CSharp에 들어갑니다. UIKit.asmdef는 autoReferenced 값이 false여서 기본 어셈블리가 자동으로 참조하지 않습니다. 따라서 Assembly-CSharp에 있는 앱 스크립트는 LoginScreen 같은 화면 리소스의 타입을 쓸 수 없습니다.

앱 스크립트에서 화면을 열려면 앱 어셈블리 정의 파일의 references에 Hive.Axyl.UIKit을 추가하세요. 레시피를 쓰려고 만든 어셈블리 정의 파일이 이미 있다면 그 파일에 추가하고, 없다면 새로 만드세요. 아래 예제의 MyApp은 앱에서 사용하는 어셈블리 이름으로 바꾸세요. 기존 설정과 참조는 그대로 유지하세요.

{
  "name": "MyApp",
  "references": [
    "Hive.Axyl.UIKit",
    "UnityEngine.UI"
  ]
}

화면 열기와 닫기

화면은 Unity 씬에 미리 놓아 두지 않고 앱 코드에서 엽니다. 저장소에도 씬은 들어 있지 않습니다. 연 화면은 앱이 직접 닫습니다.

화면 열기

화면을 열려면 로그인 화면의 LoginScreen.Show()처럼 각 화면의 Show() 메서드를 호출하세요. Show()는 UI를 표시하는 캔버스를 직접 만든 뒤 화면을 엽니다. 앱의 어느 씬에서든 Show()를 호출할 수 있습니다.

Show()에는 화면에 표시할 값과 콜백을 담은 옵션을 넘깁니다. 콜백은 사용자가 조작했을 때 화면이 호출하는 앱의 코드입니다. 아래는 로그인 화면을 열고, 닫기 요청을 받으면 화면을 닫는 예제입니다. Providers에는 표시할 로그인 수단 목록을, OnProviderSelected와 OnClose에는 콜백을 넣습니다.

LoginScreen screen = null;
screen = LoginScreen.Show(new LoginScreenOptions
{
    Providers = LoginScreenOptions.DefaultProviders(),
    OnProviderSelected = id => { /* 레시피 호출 */ },
    OnClose = () => screen.Dismiss(),
});

화면 닫기

화면은 스스로 닫히지 않습니다. 로그인에 성공했을 때처럼 화면을 닫아야 할 때는 Dismiss()를 호출하세요. 사용자가 닫기 버튼을 선택하거나 Esc를 누를 때도 화면은 OnClose만 호출하므로, OnClose에서 Dismiss()를 호출해 닫으세요. OnClose를 호출하는 조작은 화면마다 아래와 같습니다.

  • 로그인: 닫기 버튼, Esc, 화면 뒤의 어두운 배경 선택
  • 계정 관리: 닫기 버튼, Esc
  • 유저네임 로그인: 닫기 버튼, Esc. 팝업으로 열었을 때만 해당
  • 비밀번호 변경: 닫기 버튼, Esc. 팝업으로 열었을 때만 해당

유저네임 로그인 화면과 비밀번호 변경 화면은 옵션의 Popup 값이 true이면 팝업으로, false이면 전체 화면으로 열립니다. 전체 화면으로 열었을 때는 닫기 버튼이 없으므로, 앱이 다른 화면으로 넘어가는 시점에 Dismiss()를 호출해 닫으세요. 계정 관리 화면에서 확인 팝업이 열려 있을 때 Esc를 누르면 팝업만 닫히고 계정 관리 화면은 그대로 남습니다.

요청 처리 중 입력 잠금

앱이 화면에서 받은 값으로 로그인이나 비밀번호 변경 같은 요청을 처리하는 동안 입력을 잠그는 방식은 화면마다 다릅니다. 화면별로 앱이 할 일은 아래와 같습니다.

화면 입력 잠금 앱이 할 일
유저네임 로그인, 비밀번호 변경 로그인 버튼이나 확인 버튼을 선택하는 순간 화면이 입력란과 그 버튼을 스스로 잠금 처리가 끝난 뒤 화면을 계속 보여 줄 때 SetBusy(false)를 호출해 잠금 해제. 호출하지 않으면 사용자가 다시 입력할 수 없음. 처리에 성공해 화면을 닫을 때는 호출하지 않아도 됨
로그인, 계정 관리 잠금 없음. 로그인 수단 버튼이나 연동 목록 항목을 선택할 때마다 OnProviderSelected 호출 요청을 처리하는 동안 버튼이나 항목이 다시 선택되는 것을 막아야 하면 앱에서 처리

유저네임 로그인 화면과 비밀번호 변경 화면에는 로그인 버튼이나 확인 버튼으로 입력을 보내지 못하게 막는 SetSubmitEnabled()도 있습니다. 서버 점검이나 약관 미동의처럼 화면이 스스로 알 수 없는 앱의 사정으로 제출을 막아야 할 때 사용합니다.

다음 단계

가져올 화면을 정했다면 해당 화면 가이드부터 확인하세요.