가이드 및 설문 조사 iOS SDK

Amplitude의 가이드 및 설문조사 iOS SDK를 사용하면 iOS 애플리케이션에 가이드 및 설문조사를 배포할 수 있습니다.

설치 및 확인

다음 단계에 따라 SDK를 설치하고, 앱을 Amplitude 프로젝트에 연결하며, 가이드 및 설문조사가 앱에 도달하는지 확인하십시오.

요구 사항

가이드 및 설문조사 iOS SDK를 사용하려면 다음이 필요합니다.

• iOS 15 이상을 실행하는 사용자 기기.
• Swift 5.9 이상.

가이드 및 설문조사는 Amplitude 애널리틱스와 별도로 사용할 수 있습니다.

SDK 설치 및 초기화

가이드 및 설문조사는 기존 Amplitude 구현(있는 경우)과 가장 잘 작동하도록 다양한 설치 옵션을 지원합니다.

Amplitude 애널리틱스 iOS SDK 사용

앱에서 Amplitude 애널리틱스 iOS Swift SDK를 사용하는 경우, 버전 1.13.0 이상을 사용하고 있는지 확인하십시오. 그런 다음 Swift 패키지 관리자 또는 CocoaPods를 사용하여 가이드 및 설문조사 iOS SDK를 설치하십시오.

SDK 초기화

다음으로, SDK를 초기화해야 합니다.

import AmplitudeEngagementSwift
let API_KEY = "YOUR_API_KEY"
let configuration = Configuration(
  apiKey: API_KEY
)
let amplitude = Amplitude(configuration: configuration)
amplitude.add(
  plugin: AmplitudeEngagementPluginFactory.make(AmplitudeInitOptions())
)
// ----
// after calling `add`, the `engagement` SDK is available e.g. like this:
amplitude.engagement?.list()

이 호출은 Analytics 설정에 Amplitude 애널리틱스 iOS SDK의 플러그인 시스템을 사용하여 가이드 및 설문조사를 기존 분석 설정과 통합합니다. 플러그인을 추가하면 가이드 및 설문조사가 분석과 함께 초기화됩니다. 가이드 및 설문조사는 동일한 API 키와 사용자 ID를 공유하며 분석과 직접 통신합니다. 별도로 호출하실 필요는 없습니다boot.

구성 옵션

Amplitude 애널리틱스 Swift SDK 1.13.0 이상을 사용하지 않음

앱에서 Amplitude 애널리틱스 iOS Swift SDK 1.13.0 이상을 사용하지 않는 경우에도 가이드 및 설문조사를 설치할 수 있지만 분석 SDK 플러그인 시스템을 사용하는 대신 직접 .boot호출해야 합니다.

먼저, Swift 패키지 관리자 또는 CocoaPods를 사용하여 가이드 및 설문조사 iOS SDK를 설치하세요.

SDK 초기화

import AmplitudeEngagementSwift
let API_KEY = "YOUR_API_KEY"
let amplitudeEngagement = AmplitudeEngagementFactory.make(API_KEY)

구성 옵션

SDK 부팅

// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")
// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
  user_id: "USER_ID",
  device_id: "DEVICE_ID",
  user_properties: ["key": "value"]
  integrations: [
    { event, eventProperties in
      // Custom event handler
    }
  ]
)
amplitudeEngagement.boot(options: bootOptions)

프로젝트 설정에 애플리케이션 추가

SDK를 설치한 후, iOS 애플리케이션을 Amplitude 프로젝트 설정에 추가하여 가이드 및 설문조사를 만들 때 플랫폼 옵션으로 표시되도록 하세요.

애플리케이션을 추가하려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 가이드 및 설문조사 탭으로 이동합니다.
4. 앱 관리 섹션에서 확장하고 + 앱 추가를 클릭합니다.
5. 드롭다운에서 iOS를 선택합니다.

앱을 추가한 후에는 iOS 앱 사용자를 위한 가이드 및 설문조사를 만들거나 편집할 때 앱을 플랫폼 옵션으로 선택할 수 있습니다.

미리보기 모드 설정 및 확인

애플리케이션에서 직접 가이드 및 설문조사를 미리 보고 사용자에게 제공되는 것과 동일한 경험을 확인하십시오. 미리 보기를 사용하면 문구, 타겟팅 규칙 및 트리거 로직을 쉽게 반복할 수 있으며 설치가 제대로 작동하는지 확인할 수 있습니다.

모바일 URL 체계 찾기

URL 체계를 찾으려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 일반 탭으로 이동합니다.
4. URL 스키마(모바일) 필드를 찾습니다.
5. 해당 값을 복사합니다(예: amp-abcdefgh12345678).

Xcode에서 URL 스키마를 추가합니다

1. Xcode에서 iOS 프로젝트를 엽니다.
2. 프로젝트 내비게이터에서 앱의 타겟을 선택합니다.
3. Info 탭에서 URL Types 섹션을 찾거나 추가합니다.
4. 다음 값을 사용하여 새 URL 유형을 추가합니다.
   • URL 식별자: AmplitudeURLScheme와 같이 설명이 잘 되는 이름을 입력하십시오.
   • URL 구성표: Amplitude에서 복사한 값을 붙여넣습니다(예: amp-abc123).

미리보기 링크에 대한 URL 처리 구성

// In your AppDelegate or SceneDelegate
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
  if amplitudeEngagement.handleUrl(url) {
    return true
  }
  // Handle other URL schemes
  return false
}

QR 코드 스캔을 통해 설치 상태를 확인하십시오.

설치가 처음부터 끝까지 제대로 작동하는지 확인하십시오.

1. Amplitude에서 가이드 또는 설문조사를 열고 미리보기를 클릭합니다.
2. 기기의 카메라로 표시된 QR 코드를 스캔하거나, 앱이 설치된 기기에서 미리보기 URL을 엽니다.
3. 앱 내에서 가이드 또는 설문조사가 열리는지 확인하십시오.
4. 화면 하단에 있는 작은 Amplitude 로고를 찾아 누르면 슈퍼 디버거가 열립니다. 여기서 확인할 내용은 슈퍼 디버거를 참조하십시오.

앱에서 미리보기가 열리지 않거나 로고가 나타나지 않는 경우, 계속하기 전에 위의 URL 구성표 설정 단계를 검토하세요.

참조

최소 SDK 버전 설정(필요한 경우)

SDK 버전 3.0.0및 이후 버전에서 지원합니다Minimum SDK version. 이전 SDK 릴리스에서 심각한 문제를 확인할 때 이 설정을 안전 제어로 사용하십시오.

최소 SDK 버전을 구성하려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 가이드 및 설문조사 탭으로 이동합니다.
4. 앱 관리 섹션에서 확장하고 + 앱 추가를 클릭합니다.
5. 드롭다운에서 iOS를 선택합니다.
6. 최소 SDK 버전에 값을 입력합니다.

이 값을 설정하면 가이드 및 설문조사는 각 앱 빌드의 SDK 버전과 구성된 최소 값을 비교합니다.

• 앱 빌드에서 이전 SDK 버전을 사용하는 경우 SDK가 해당 빌드에서 초기화되지 않습니다.
• 앱 빌드에서 동일하거나 최신 버전의 SDK를 사용하는 경우 SDK가 예상대로 초기화됩니다.

이 설정을 사용하면 애플리케이션 릴리스를 롤백하지 않고 문제가 있는 알려진 SDK 버전에서 가이드 및 설문조사를 중지할 수 있습니다.

최소 SDK 버전의 사용 예제

앱 버전 120이 가이드 및 설문조사 SDK 3.0.2를 사용하고, 앱 버전 121이 버그 수정이 포함된 가이드 및 설문조사 SDK 3.1.0를 사용한다고 가정해 보겠습니다. 최소 SDK 버전을 다음과 같이 3.1.0설정한 경우

• 앱 버전120은 더 이상 가이드 및 설문조사를 로드하지 않습니다.
• 앱 버전121은 계속해서 가이드 및 설문조사를 로드합니다.

설치 문제 해결

Swift 패키지 관리자에서 버전 업그레이드 문제 해결

SDK 버전을 업그레이드했지만 여전히 예기치 않은 동작이 발생하는 경우, Xcode가 이전 버전의 캐시된 빌드 아티팩트를 사용하고 있을 수 있습니다. SPM 캐시를 지우려면 다음과 같이 하십시오.

1. 명령줄 인터페이스(예: 터미널) 또는 파일 관리 앱(예: Finder)에서 ~/Library/Caches/org.swift.swiftpm/repositories로 이동합니다.
2. Amplitude Engagement Swift 패키지와 관련된 폴더 및 잠금 파일을 삭제하십시오.
3. Xcode에서 File > Swift Packages > Reset Package Caches 를 실행합니다.
4. 그런 다음 _File > Packages > Resolve Package Versions_를 실행합니다.

문제가 지속되면 다음 방법을 시도하여 전체 캐시를 재설정하십시오.

rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf ~/Library/org.swift.swiftpm
rm -rf ~/Library/Developer/Xcode/DerivedData

CocoaPods 설치 문제 해결

코코아팟을 AmplitudeEngagementSwift사용하여 가져올 때 오류가 발생하면 .swiftinterface파일의 줄 끝이 잘못되었기 때문일 가능성이 큽니다Error extracting version from module interface. 같은 Git 설정은 이러한 파일을 LF에서 CRLF로 다시 작성할 core.autocrlf수 있습니다.

이 문제를 해결하려면 프로젝트 루트의 .gitattributes파일에 다음 줄을 추가하십시오.

*.swiftinterface text eol=lf
Pods/** -text

이 줄을 추가한 후 빌드 폴더를 정리하고 프로젝트를 다시 빌드하십시오.

화면 추적 및 요소 타겟팅

화면 추적 및 요소 타겟팅은 선택 사항이지만 가이드 및 설문조사를 보다 정확하게 만드는 데 도움이 됩니다.

화면 추적 활성화

화면 기반 타겟팅 및 화면 시간 트리거를 호출하십시오screen. 가이드 및 설문조사는 화면 문자열(예: '홈스크린')을 가이드 또는 설문조사 페이지 타겟팅 섹션의 문자열과 비교합니다.

// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")

요소 타겟팅 활성화

핀, 툴팁 및 카드 삽입 가이드는 SDK가 화면의 특정 요소를 대상으로 하는 데 필요합니다. 앱에서 요소 타겟팅을 활성화하려면 요소에 고유 식별자를 지정하십시오.

// Swift UI
MySwiftView {
  // Content
}
.amplitudeView("MySwiftView", onTrigger: {
  // Optional code to run with tap element action
})
// UIKit: set an accessibility identifier so the SDK can target the view
let myView = MyUIKitView(...)
myView.accessibilityIdentifier = "MyView"
let tapGesture = UITapGestureRecognizer(target: self, action: #selector(myButtonAction))
myView.addGestureRecognizer(tapGesture)
myView.isUserInteractionEnabled = true
// Note: To use the tap element action from a guide or survey on your UIKit view,
// explicitly add a target to the view in addition to any gesture recognizers you may have added.
myView.addTarget(self, action: #selector(myButtonAction), for: .touchUpInside)
@objc func myButtonAction() {
  // Optional code to run on tap / tap element action
}

현지화

초기화 다음 기간동안 locale옵션을 설정하여 가이드 또는 설문조사를 현지화합니다. 언어나 로케일을 설정하지 않은 경우, Amplitude는 기본 언어를 사용합니다.

// Set locale during initialization
let configuration = Configuration(apiKey: API_KEY)
amplitude.add(
  plugin: AmplitudeEngagementPluginFactory.make(
    AmplitudeInitOptions(locale: "fr-FR")
  )
)

SDK가 초기화된 후 언어를 동적으로 업데이트하려면 updateLanguage메서드를 사용하십시오. updateLanguage를 호출하면 새 로케일로 구성을 다시 가져옵니다.

// Example: Update language to French with full locale
amplitudeEngagement.updateLanguage("fr-FR")
// Example: Update language to English with language code
amplitudeEngagement.updateLanguage("en")

기타 SDK 방법

SDK 활성화 및 비활성화

가이드 및 설문조사가 disable()일시적으로 표시되지 않도록 하고 현재 표시된 전체 가이드 및 설문조사를 숨길 때 사용합니다. 정상 작동을 재개하는 데 enable()사용하십시오.

// Temporarily disable the SDK
amplitudeEngagement.disable()
// Re-enable the SDK
amplitudeEngagement.enable()

타겟팅 데이터 새로 고침

사용자 속성 업데이트 후 Amplitude에서 타겟팅 평가를 다시 가져오는 데 사용하십시오refresh(). 가이드 또는 설문조사가 표시될 경우 SDK는 새로 고침을 건너뛰습니다.

amplitudeEngagement.refresh()

자동 새로 고침 간격 설정

타겟팅 데이터의 주기적 새로 고침을 활성화합니다. 부팅 후에 이 옵션을 호출하여 간격을 변경하거나 비활성화할 수 있습니다. 활성화된 경우 최소 간격은 60초입니다. 비활성화하려면 0로 설정하거나 음수 값을 입력하십시오.

amplitudeEngagement.setAutoRefreshInterval(seconds: 3600) // Every hour
amplitudeEngagement.setAutoRefreshInterval(seconds: 0)    // Disable

테마 관리

앱이 밝은 모드와 어두운 모드를 지원하는 경우 시각적 테마 모드를 구성하십시오.

// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: AUTO, LIGHT, DARK

콜백 등록

가이드 또는 설문조사 버튼에 콜백 실행 동작을 설정하여 콜백을 실행합니다.

engagement.addCallback(_ key: String, _ function: () -> Void)

engagement.addCallback("show-alert") {
  DispatchQueue.main.async {
    let alert = UIAlertController(
      title: "Callback",
      message: "Callback has been executed!",
      preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "OK", style: .default))
    viewController.present(alert, animated: true)
  }
}

라우터 구성

가이드 및 설문조사가 화면 탐색을 처리하는 방법을 구성합니다.

engagement.setRouter { identifier in
  // Your screen handling and navigation
}

라우터를 제거하려면 unsetRouter()를 호출하십시오.

amplitudeEngagement.unsetRouter()

재설정

안내서 또는 설문조사를 특정 단계로 재설정합니다.

amplitudeEngagement.reset(key: "GUIDE_KEY", stepIndex: 0)

목록

모든 라이브 가이드 및 설문조사의 목록과 해당 상태를 검색합니다.

let guidesAndSurveys = amplitudeEngagement.list()

보기

특정 가이드 또는 설문조사를 표시합니다. 화면 타겟팅을 제외한 전체 타겟팅 규칙과 제한을 무시합니다.

amplitudeEngagement.show(key: "GUIDE_KEY")

전달 이벤트

Amplitude 애널리틱스 iOS SDK 플러그인을 사용하지 않는 경우(즉, boot직접 호출한 경우), forwardEvent를 사용하여 가이드 및 설문조사에서 On 이벤트 추적 트리거를 활성화하십시오. 전달된 이벤트는 Amplitude 서버로 전송되지 않습니다. SDK는 이를 로컬 트리거 평가에만 사용합니다.

amplitudeEngagement.forwardEvent([
  "event_type": "my event type",
  "event_properties": [String: String]()
])

스마트 상호 작용 재설정

분노 탭, 사용자 비활성 상태 및 요소 탭 감지 등 스마트 상호 작용 감지기에서 캐시된 상태를 모두 지우려면 resetSmartInteractions()호출하십시오.

amplitudeEngagement.resetSmartInteractions()

모두 닫기

모든 활성 가이드 및 설문조사를 닫습니다.

amplitudeEngagement.closeAll()

슈퍼 디버거

Amplitude 대시보드에서 미리보기 QR 코드를 스캔하면 화면 하단에 작은 Amplitude 로고가 나타납니다. 이를 눌러 슈퍼 디버거 패널을 엽니다.

슈퍼 디버거에는 세부 정보와 설정이라는 두 가지 탭이 있습니다.

세부 정보 탭

세부 정보 탭에는 미리 보고 있는 가이드 또는 설문조사에 대한 정보가 표시되며 미리 보기 세션을 검토하고 제어할 수 있습니다.

가이드/설문조사: 활성 가이드나 설문조사의 이름입니다. 이를 탭하여 다른 가이드나 설문조사로 전환하세요.

세부 정보:

• 단계: 총 단계 중 현재 단계 번호입니다(예: "3단계 중 1"). 복사 아이콘을 눌러 값을 복사합니다.
• 사용자: 미리 보기 세션의 사용자 ID입니다. 복사 아이콘을 눌러 이를 복사합니다.
• 화면: SDK가 현재 보고하는 화면 이름입니다. 복사 아이콘을 눌러 이를 복사합니다.

디버그: 가이드 또는 설문조사가 각 조건 검사를 통과했는지 여부를 표시합니다. 각 행은 확장되어 세부 정보를 표시합니다.

• 제한: 가이드 또는 설문조사가 표시 제한에 도달했는지 여부입니다. 확장하여 구성된 제한을 검토합니다.
• 트리거: 가이드 또는 설문조사가 트리거 조건을 충족하는지 여부입니다. 트리거 유형, 화면 조건 및 핀 대상 요소(해당되는 경우)를 검토하려면 확장합니다.
• 스로틀: 가이드 또는 설문조사가 스로틀 조건을 충족하는지 여부입니다. 스로틀 설정을 검토하려면 확장합니다. 미리보기 세션 동안 스로틀 제한을 우회하려면 제한 무시를 토글합니다.

고급:

• 핀 디버깅: 5초마다 핀 위치 변경을 활성화하도록 확장합니다. 디버거는 동적 레이아웃에서의 핀 배치를 디버깅하는 데 도움이 되도록 핀 위치를 정기적으로 재평가합니다.

패널 맨 아래에:

• 미리 보기 다시 시작: 가이드 또는 설문조사를 첫 번째 단계로 재설정하고 미리 보기를 다시 시작합니다.
• 미리 보기 닫기: 미리 보기 모드를 종료하고 수퍼 디버거를 종료합니다.

설정 탭

설정 탭에는 현재 세션에 대한 SDK 구성 및 환경 세부 정보가 표시됩니다.

SDK 버전: 앱에 설치된 참여 SDK의 버전입니다.

설치:

• 유형: SDK 설치 방법(예: 플러그인 또는 독립형)입니다.
• 구성: 적용된 사용자 지정 구성 옵션의 수와 유형입니다.

사용자:

• 사용자 ID: 부팅 시 SDK에 전달된 사용자 ID입니다.
• 속성: 현재 세션에 대해 설정된 사용자 속성입니다.

이벤트 흐름: 이벤트가 올바르게 흐르고 있는지 확인합니다:

• 가이드 및 설문조사 SDK로 흐르는 이벤트: 분석 인스턴스의 이벤트는 참여 SDK에 도달합니다.
• 가이드 및 설문조사 SDK에서 발생하는 이벤트: 참여 SDK는 이벤트를 Amplitude로 전송합니다.

지원

**?**를 누르십시오. 지원 패널을 여는 버튼입니다. 여기에서 다음을 수행할 수 있습니다.

• SDK 문서와 가이드 및 설문조사 요약에 대한 링크를 엽니다.
• 버그 리포트 제출: 디버거에서 직접 버그 리포트를 제출합니다. 재현할 단계, 예상 결과 및 실제 결과를 입력한 다음 보내기를 누릅니다.

알려진 제한 사항

오프라인 지원 없음

SDK는 가이드 및 설문조사를 가져오고 표시하기 위해 활성 인터넷 연결이 필요합니다. 앱이 처음 로드될 때 기기가 오프라인 상태인 경우 해당 앱 세션에 대해 가이드 및 설문조사가 표시되지 않습니다.

탭 바 요소 타겟팅

핀과 툴팁은 탭 막대 항목(예: UITabBar요소)을 대상으로 삼을 수 없습니다. 탭 막대는 표준 뷰 계층 구조 외부에 존재하는 시스템 수준의 구성 요소를 사용하므로 SDK가 이러한 요소에 가이드를 안정적으로 찾아 연결할 수 없습니다.

애니메이션된 요소와 움직이는 컨테이너 내부의 요소를 대상으로 설정

핀과 툴팁은 다음과 같은 뷰나 요소를 대상으로 삼을 수 없습니다.

• 애니메이션되거나 애니메이션된 컨테이너에 있습니다(화면 주위를 이동).
• 사용자 상호 작용에 따라 이동할 수 있는 컨테이너에 있습니다.

변경 기록

Mobile SDK 변경 기록으로 이동하십시오.