Akan.js
Docs
문서컨벤션레퍼런스Cheatsheet
Akan.js
문서컨벤션레퍼런스Cheatsheet
Akan.js

MIT 라이선스 하에 배포되었습니다.

Akan.js 공식 컨설팅 서비스AkansoftCopyright © 2026 Akan.js 모든 권리 보유.시스템 관리자bassman
사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
일반▾
인증과 권한에이전트를 위한 OAuth스키마 설계텍스트 검색엣지 컴퓨팅파일 관리Single Sign-OnDataList & Enum
인터페이스▾
CRUDEndpointMCP 서버에이전트 채팅Form
관측성▾
로깅의존성 주입에러 처리메트릭
성능▾
캐싱이미지 최적화지연 로딩쿼리변경큐실시간
모바일▾
설정Push NotificationsDeep LinksUI & Keyboard데스크톱 배포
개발▾
문서화스키마 문서스크립트콘솔도커쿠버네티스PWA테스트
사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
일반▾
인증과 권한에이전트를 위한 OAuth스키마 설계텍스트 검색엣지 컴퓨팅파일 관리Single Sign-OnDataList & Enum
인터페이스▾
CRUDEndpointMCP 서버에이전트 채팅Form
관측성▾
로깅의존성 주입에러 처리메트릭
성능▾
캐싱이미지 최적화지연 로딩쿼리변경큐실시간
모바일▾
설정Push NotificationsDeep LinksUI & Keyboard데스크톱 배포
개발▾
문서화스키마 문서스크립트콘솔도커쿠버네티스PWA테스트
이전Push Notifications다음UI & Keyboard

딥 링크 설정

딥 링크는 앱 바깥의 URL로 앱 안의 특정 화면을 바로 여는 기능입니다. 메시지 속 링크나 푸시 알림을 누르면 해당 화면이 열립니다. 설정은 akan.config.ts의 native 섹션에서 끝납니다. deepLinks가 링크를 정하고, ios와 android가 도메인을 검증할 값을 가집니다.
링크 방식 두 가지
딥 링크는 기능 이름이고, schemes와 domains는 그것을 구현하는 대표적인 두 방식입니다. 둘을 함께 선언해도 됩니다:
scheme 링크 · schemes
shop://orders/1
앱 전용 링크입니다. 검증이 필요 없어 개발 중에 테스트하기 쉽습니다.
domain 링크 · domains
https://shop.example.com/orders/1
일반 웹 링크처럼 동작하지만 iOS·Android 검증이 필요합니다. 공유, 이메일, 푸시 알림 URL에 더 적합합니다.
설정하기
native에 deepLinks를 적고, 도메인을 검증할 값은 그 안의 ios와 android 섹션에 적습니다:
apps/myapp/akan.config.ts
  • 모든 target이 이 값을 받습니다. target이 schemes나 domains를 적으면 그 목록을 바꾸며, 이어 붙이지 않습니다.
  • domains에는 호스트만. shop.example.com처럼 적습니다. https://나 경로는 붙여도 무시됩니다.
  • ios.teamId·android.sha256CertFingerprints는 domains용입니다. scheme 링크만 쓴다면 둘 다 생략합니다.
  • 앱을 다시 실행해야 적용됩니다. 설정을 바꾼 뒤에는 akan start-ios나 akan start-android를 다시 실행합니다.
링크가 여는 화면
scheme 링크, domain 링크, 푸시 알림의 data.url은 모두 같은 CSR route를 엽니다:
들어온 링크여는 화면
shop://orders/1
scheme 링크입니다. orders가 경로의 첫 부분이 되어 /orders/1을 엽니다.
https://shop.example.com/orders/1
domain 링크입니다. 경로를 그대로 써서 /orders/1을 엽니다.
data.url = "/orders/1"
푸시 알림을 누른 경우입니다. 같은 방식으로 /orders/1을 엽니다.
꺼진 앱에서 열려도 뒤로 가기가 됩니다. 링크로 앱이 켜지면 상위 화면이나 시작 화면을 먼저 쌓아, 뒤로 가기가 앱 안에서 동작합니다.
native 설정→
target과 native 블록의 나머지 설정.
푸시 알림→
알림을 누르면 화면이 열리도록 url을 보내는 법.

링크 필드

모든 필드는 선택입니다. 플랫폼마다 필요한 값만 읽으므로, 고른 링크 방식에 필요한 것만 적으면 됩니다:
deepLinks.schemesstring[]
shop://orders/1의 shop처럼 앱 전용 URL scheme입니다.
deepLinks.domainsstring[]
HTTPS 링크를 앱으로 여는 호스트입니다. iOS와 Android가 검증한 뒤에 동작합니다.
ios.teamIdstring
Apple Developer Team ID입니다. iOS가 domains를 검증할 때 씁니다.
android.sha256CertFingerprintsstring[]
앱을 서명한 인증서의 SHA-256 fingerprint입니다. Android가 domains를 검증할 때 씁니다.
링크 방식별로 필요한 필드
scheme 링크는 필드 하나면 되고, domain 링크는 세 개가 필요합니다. 플랫폼은 그중 자기 몫만 읽습니다:
필드
iOS
Android
scheme 링크
deepLinks.schemes
✓
✓
domain 링크
deepLinks.domains
✓
✓
ios.teamId
✓
android.sha256CertFingerprints
✓
✓이 플랫폼이 읽음읽지 않음
도메인 검증
domain 링크는 그 도메인이 이 앱의 것임을 플랫폼이 확인한 뒤에야 앱으로 열립니다. 확인은 도메인이 내려주는 파일로 합니다:
  • 두 파일은 Akan 서버가 응답합니다. 이 필드로 /.well-known/apple-app-site-association과 /.well-known/assetlinks.json을 만들어 주므로, 도메인이 앱 서버를 가리키게 하고 필드를 바꾸면 서버도 다시 배포합니다.
  • iOS는 Team ID와 appId를 봅니다. 파일에 ios.teamId와 target의 appId로 만든 <teamId>.<appId>가 들어가므로 둘 다 실제 값이어야 합니다.
  • Android는 서명 인증서를 봅니다. debug 빌드와 release 빌드는 서로 다른 키로 서명되므로 fingerprint를 둘 다 적습니다.
  • debug 빌드는 main이 아닌 서버에서만 검증됩니다. debug 빌드의 패키지 이름은 .debug로 끝나는데, assetlinks.json은 AKAN_PUBLIC_ENV가 main이 아닐 때만 이 이름을 넣습니다. debug 키의 SHA-256도 sha256CertFingerprints에 있어야 합니다.
플랫폼 공식 문서
  • iOS — Universal Links
  • Android — App Links
Android fingerprint 구하기
빌드를 서명하는 keystore에서 읽습니다. debug 빌드는 첫 Android 빌드가 만든 런타임 전용 debug keystore로 서명합니다:
Terminal
release 빌드는 akan release-android가 환경 변수에서 읽는 upload key로 서명합니다:
Terminal
  • Play App Signing을 쓰면 Google의 키도 적습니다. Play가 업로드한 빌드를 다시 서명하므로 설치된 앱은 앱 서명 키를 씁니다. Play Console(설정 › 앱 서명)에서 SHA-256을 복사해 upload key, debug key 옆에 적습니다.
검증에 실패한 domain 링크는 앱이 아니라 브라우저에서 열립니다. 지금 설치된 빌드를 서명한 키의 fingerprint가 목록에 있어야 합니다.

이 페이지

딥 링크 설정
링크 필드