딥 링크

개요

외부에서 앱을 열거나 앱 내 특정 화면으로 이동하는 딥링크를 지원합니다.

기능	Android	iOS
커스텀 스킴 딥링크	✓	✓
App Links (HTTPS)	✓	✓ (Universal Links)

지원 플랜: Basic 이상

딥링크 스킴 구조

빌드 플레이버별 기본 딥링크 스킴:

플레이버	기본 스킴
Basic	`unveily-basic://`
Standard	`unveily-standard://`
Pro	`unveily-pro://`

커스텀 스킴은 app/build.gradle.kts의 deepLinkScheme 플레이스홀더에서 변경합니다.

딥링크 URL 예시

unveily-basic://product?id=1234
unveily-basic://user/profile

딥링크 수신 처리

앱이 딥링크로 열리면 이벤트가 발생합니다.

window.addEventListener('unveily-event', (e) => {
  if (e.detail.type === 'deeplink') {
    const { url } = e.detail.data;
    handleDeepLink(url);
  }
});

function handleDeepLink(url) {
  const parsed = new URL(url);
  const path = parsed.pathname;     // "/product"
  const params = parsed.searchParams;

  if (path === '/product') {
    const productId = params.get('id');
    window.location.href = `/product/${productId}`;
  }
}

App Links (HTTPS 딥링크)

Android App Links를 사용하면 https://your-domain.com/path 형식의 URL로 앱을 열 수 있습니다.

1. assetlinks.json 서버 배포

/.well-known/assetlinks.json 경로로 접근 가능해야 합니다.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourcompany.app",
    "sha256_cert_fingerprints": ["AA:BB:CC:DD:..."]
  }
}]

sha256_cert_fingerprints는 Google Play Console의 앱 서명 섹션에서 확인할 수 있습니다.

iOS Universal Links 설정

iOS에서 HTTPS URL로 앱을 열려면 Universal Links를 설정해야 합니다.

1. apple-app-site-association 파일 서버 배포

/.well-known/apple-app-site-association 경로에 JSON 파일을 제공해야 합니다. 확장자 없이 배포하며, Content-Type: application/json으로 응답해야 합니다.

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.yourcompany.app",
        "paths": ["/product/*", "/user/*"]
      }
    ]
  }
}

appID는 {Apple Team ID}.{Bundle ID} 형식입니다. Team ID는 Apple Developer 콘솔의 Membership 섹션에서 확인할 수 있습니다.

2. Xcode에서 Associated Domains 활성화

Xcode → Signing & Capabilities → Associated Domains 추가 후 도메인을 입력합니다.

applinks:your-domain.com

서버에서 assetlinks.json 제공

app.get('/.well-known/assetlinks.json', (req, res) => {
  res.json([{
    relation: ['delegate_permission/common.handle_all_urls'],
    target: {
      namespace: 'android_app',
      package_name: 'com.yourcompany.app',
      sha256_cert_fingerprints: [process.env.APP_CERT_FINGERPRINT]
    }
  }]);
});

app.MapGet("/.well-known/assetlinks.json", () => new[] {
    new {
        relation = new[] { "delegate_permission/common.handle_all_urls" },
        target = new {
            @namespace = "android_app",
            package_name = "com.yourcompany.app",
            sha256_cert_fingerprints = new[] { Environment.GetEnvironmentVariable("APP_CERT_FINGERPRINT") }
        }
    }
});

@GetMapping("/.well-known/assetlinks.json")
public ResponseEntity<List<Map<String, Object>>> assetLinks() {
    return ResponseEntity.ok(List.of(Map.of(
        "relation", List.of("delegate_permission/common.handle_all_urls"),
        "target", Map.of(
            "namespace", "android_app",
            "package_name", "com.yourcompany.app",
            "sha256_cert_fingerprints", List.of(certFingerprint)
        )
    )));
}

<?php
if ($_SERVER['REQUEST_URI'] === '/.well-known/assetlinks.json') {
    header('Content-Type: application/json');
    echo json_encode([[
        'relation' => ['delegate_permission/common.handle_all_urls'],
        'target' => [
            'namespace' => 'android_app',
            'package_name' => 'com.yourcompany.app',
            'sha256_cert_fingerprints' => [$_ENV['APP_CERT_FINGERPRINT']]
        ]
    ]]);
    exit;
}

<%
Response.ContentType = "application/json"
Dim fingerprint
fingerprint = Application("AppCertFingerprint")
Response.Write "[{""relation"":[""delegate_permission/common.handle_all_urls""]," & _
    """target"":{""namespace"":""android_app""," & _
    """package_name"":""com.yourcompany.app""," & _
    """sha256_cert_fingerprints"":[""" & fingerprint & """]}}]"
%>

개요

딥링크 스킴 구조

딥링크 수신 처리

App Links (HTTPS 딥링크)

iOS Universal Links 설정

서버에서 assetlinks.json 제공

On this page