WeChat 미니 프로그램용 Mega 플러그인 샘플 프로젝트 빠르게 실행

이 문서는 WeChat 미니 프로그램용 Mega 플러그인의 샘플 프로젝트를 빠르게 실행하는 방법을 소개합니다. 다음을 배우게 됩니다.

샘플 프로젝트의 개발 환경을 구축하고 구성합니다.
샘플의 일부 기능을 실행하여 Mega 클라우드 위치 확인을 사용합니다.
매핑 결과의 마스크 파일을 표시하고 모델이 실제 환경과 정렬되는지 확인합니다.

시작하기 전에

위치 확인 기능을 사용할 수 있나요?를 참고하여 위치 확인 데이터베이스가 올바르게 생성되고 지도가 추가되었는지 확인합니다.

미니 프로그램 주체가 기업인지 확인

중요

Mega 미니 프로그램 플러그인은 기업 주체의 WeChat 미니 프로그램만 지원합니다. 개인 주체의 미니 프로그램은 이 플러그인을 사용할 수 없습니다.

미니 프로그램 관리 페이지에서 설정 > 기본 정보 > 주체 정보가 기업 법인 또는 개인사업자로 표시되는지 확인하세요.

Mega 기능은 미니 프로그램 플러그인으로 제공되므로, 호스트가 될 기업 주체의 WeChat 미니 프로그램이 필요합니다.

제공된 샘플 프로젝트만 실행하는 경우에도 개발자 도구에서 디버깅과 미리보기를 하려면 자신의 WeChat 미니 프로그램 AppID를 설정해야 합니다.

샘플 프로젝트 다운로드

개발 도구 다운로드 페이지로 이동합니다.
_EasyAR 개인정보 처리방침_을 확인한 후 다운로드를 클릭합니다.
다운로드가 완료되면 로컬에서 .zip 파일의 압축을 풉니다.

샘플 프로젝트 구성

WeChat 미니 프로그램 개발자 도구에 로그인합니다.
WeChat 미니 프로그램 개발자 도구에서 샘플 프로젝트를 가져옵니다.
- 개발자 도구를 열고 가져오기 버튼을 클릭한 다음 로컬에서 압축 해제한 폴더를 선택합니다.
- AppID가 Mega 라이선스 신청 시 입력한 AppID와 같은지 확인하고 개발 모드를 미니 프로그램으로 설정한 뒤 만들기를 클릭합니다.
참고

AppID가 일치하지 않으면 라이선스 검증에 실패합니다
Mega 라이선스 및 클라우드 서비스 구성

miniprogram/components/sample-data/easyar-settings.ts 파일을 열고 준비 단계의 라이선스 및 서비스 정보에 따라 해당 필드를 입력합니다.
- Mega 라이선스
```
/** Mini Program용 Mega 라이선스 */
export const EasyARLicenseKey: string = "";
```
Mega WeChat Mini Program 라이선스 받는 방법

EasyAR Developer Center에서 Mega WeChat Mini Program을 선택합니다.

사용할 Mega WeChat Mini Program 라이선스가 목록에 있어야 합니다. 사용 가능한 라이선스가 없다면 현재 계정이 Mega 로컬라이제이션 데이터베이스를 만든 계정과 같은지 확인하십시오.

Mini Program 이름을 클릭하여 해당 Mega 라이선스를 가져옵니다. 오른쪽의 Copy를 클릭한 뒤 easyar-settings.ts에 EasyARLicenseKey 값으로 붙여 넣고, 연결된 AppID가 WeChat Mini Program AppID와 완전히 일치하는지 확인합니다.
- 클라우드 서비스 API Key 및 Seceret
```
/** 클라우드 서비스 API Key 및 Seceret */
export const EasyARAPIKey: string = "";
export const EasyARAPISecret: string = "";
```
클라우드 서비스 API Key 및 Seceret을 얻는 방법

EasyAR Developer Center에서 Cloud Service API KEY를 선택합니다.

이전에 클라우드 서비스 API Key 및 Seceret을 만든 적이 있다면 오른쪽의 Copy를 순서대로 클릭하고 easyar-settings.ts에 EasyARAPIKey와 EasyARAPISecret 값으로 붙여 넣습니다.

이전에 클라우드 서비스 API Key 및 Seceret을 만든 적이 없다면 다음 방식으로 만듭니다.

EasyAR Developer Center에서 Cloud Service API KEY > Create API KEY를 선택합니다.

애플리케이션 이름을 입력하고 사용할 클라우드 서비스 Mega Block 및/또는 Mega Landmark를 선택한 뒤 Confirm을 클릭합니다.
- 클라우드 서비스 ServerAddress 및 AppID：
```
/** Mega 클라우드 로컬라이제이션 데이터베이스의 ServerAddress 및 AppID */
export const MegaTrackerServerAddress: string = "";
export const MegaTrackerAppID: string = "";
```
Mega 클라우드 로컬라이제이션 데이터베이스의 ServerAddress 및 AppID를 얻는 방법

EasyAR Developer Center에서 Block Cloud Localization을 선택한 뒤 자신의 Mega 클라우드 로컬라이제이션 서비스 그룹을 선택합니다.

자신의 Mega 클라우드 로컬라이제이션 데이터베이스를 선택합니다.

Key를 클릭한 뒤 아래에서 클라우드 로컬라이제이션 데이터베이스의 AppID와 Server Address를 순서대로 가져옵니다. 오른쪽의 Copy를 클릭하고 easyar-settings.ts에 MegaTrackerAppID와 MegaTrackerServerAddress 값으로 붙여 넣습니다.
매핑 결과의 마스크 파일로 빠르게 검증

클라우드 위치 확인 데이터베이스의 마스크 파일 다운로드에서 매핑 결과의 glb 마스크 파일을 받을 수 있습니다. 실제 공간의 3D 흰색 모델을 표시해 주석을 만들지 않고 정렬 상태를 확인할 수 있습니다.

참고

이 방법은 매핑 버전 9.6 이상의 결과에만 적용됩니다.

클라우드 위치 확인 데이터베이스에서 테스트할 Block을 찾아 해당 행의 작업 열에서 마스크 파일 다운로드를 클릭합니다. 실행할 때는 이 Block에 해당하는 현장에서 테스트하세요.

팝업에서 저정밀도를 선택하고 다운로드를 클릭하면 휴대폰의 로딩 및 렌더링 부담을 줄일 수 있습니다.

다운로드한 glb 파일을 Mini Program 프로젝트의 assets 디렉터리(예제에서는 miniprogram/assets/)에 넣고 각 모델의 원래 위치, 회전, 크기를 유지합니다.

miniprogram/components/sample-easyar-mega/index.ts에서 occlusionMeshAssets 설정의 src를 Mini Program 프로젝트 루트 기준 상대 경로로 변경합니다. 기본 설정은 다음과 같습니다:
```
const occlusionMeshAssets = [
    {
        assetId: "occlusionMesh00",
        type: "gltf",
        src: "assets/Low_Poly_occlusion.glb",
        options: {}
    },
];
```
다운로드한 마스크에 GLB 파일이 여러 개 포함되어 있다면 각 파일에 대해 고유한 assetId와 해당 src를 가진 항목을 occlusionMeshAssets에 추가합니다. 예제는 파일을 로드하고 마스크 메시를 위치가 확인된 Block에 연결한 뒤 기본 제공 표시 및 가림 머티리얼을 적용합니다. 페이지의 마스크 파일 스위치로 메시를 표시하거나 숨깁니다. 리소스는 예제 컴포넌트와 함께 해제되므로 추가 로드 또는 해제 로직은 필요하지 않습니다.

실제 기기에서 샘플 실행

미니 프로그램 개발자 도구 상단의 실기기 미리보기 버튼을 클릭하고 QR 코드를 스캔하여 개발용 휴대폰에 프로젝트를 불러옵니다.

주의

AR 기능이 있는 xr-frame 컴포넌트는 개발자 도구의 시뮬레이터에서 직접 실행할 수 없습니다.

참고

WeChat 개발자 도구에서 샘플 프로젝트를 처음 실행할 때 플러그인 권한이 없으면 미승인 알림이 표시될 수 있습니다. 개발자 도구에서 승인하거나 플러그인 연동 절차를 참고하세요.
EasyAR Mega Samples를 클릭하여 샘플 프로젝트의 AR 장면을 엽니다.

참고

AR 장면이 열리지 않으면 기기가 WeChat VisionKit을 지원하지 않을 수 있습니다. 기기 제한을 참고하세요.
화면에 EasyAR Session is initializing이 표시되면 WeChat 평면 감지가 초기화 중입니다.

팁

조명이 충분한 환경에서 테스트하고 넓은 단색 벽면이나 단색 바닥은 피하십시오.

바닥이나 다른 평면을 향해 휴대폰을 일정한 속도로 좌우로 움직이면 초기화가 빨라집니다.
초기화 후 휴대폰을 세로로 들고 카메라로 실제 환경을 비춥니다. 위치 확인에 성공하면 Debug 정보에 Found가 표시되고 오른쪽 아래의 상태 표시기가 흰색에서 녹색으로 바뀝니다.
마스크 파일과 실제 환경의 정렬 상태 확인

마스크 파일 표시 설정을 마친 후 모델 로드와 해당 Block의 위치 확인이 완료될 때까지 기다립니다. 페이지에서 마스크 파일 스위치를 켜면 카메라 화면 위에 3D 흰색 모델이 표시되며 실제 환경과 정렬되는지 확인할 수 있습니다.