사람함께에이전트▾

사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.

함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.

에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.

일반▾

인증과 권한 에이전트를 위한 OAuth 스키마 설계 텍스트 검색 엣지 컴퓨팅 파일 관리 Single Sign-On DataList & Enum

인터페이스▾

CRUD Endpoint MCP 서버 에이전트 채팅 Form

관측성▾

로깅 의존성 주입 에러 처리 메트릭

성능▾

캐싱 이미지 최적화 지연 로딩 쿼리 변경 큐 실시간

모바일▾

설정 Push Notifications Deep Links UI & Keyboard 데스크톱 배포

개발▾

문서화 스키마 문서 스크립트 콘솔 도커 쿠버네티스 PWA 테스트

딥 링크 설정

딥 링크는 앱 바깥의 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가 목록에 있어야 합니다.

이전Push Notifications 다음UI & Keyboard