NowAnalyticsService 프로토콜 - iOS

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 13분

    • NowAnalyticsService 프로토콜은 사용자 분석 데이터 수집을 관리하기 위한 분석 속성, 사용자 설정 및 이벤트를 구성할 수 있는 기능을 제공합니다.

    이 프로토콜을 준수하는 객체는 sharedAnalyticsService에 의해 반환됩니다. 애플리케이션에서 이를 사용하여 API 호출을 수행합니다.

    표 1. 요구 사항
    이름 유형 설명
    trackingConsent 부울 사용자가 연결된 장치에 대한 분석 추적에 동의했는지 여부를 나타내는 플래그입니다. 기본적으로 장치는 옵트아웃되어 있습니다. 이 값을 명시적으로 false 로 설정하면 진행 중인 세션이 즉시 종료되고 로컬로 기록된 데이터가 삭제됩니다.
    유효한 값은 다음과 같습니다.
    • true: 사용자가 이 장치에서 분석 데이터를 추적하는 데 동의했습니다.
    • false: 사용자가 데이터 추적을 거부했습니다.

    NowAnalyticsService - addEvent(명명된 eventName: 문자열, 속성: [문자열: 임의]?)

    사용자가 특정 수준이나 화면에 도달하는 것과 같은 애플리케이션 이벤트를 추가하고 이벤트에 대한 사용자 지정 속성 설정을 활성화합니다. 이러한 이벤트는 발생한 순서대로 대시보드에 나타납니다.

    이러한 이벤트는 분석 대시보드에 나타납니다.

    표 2. 매개변수
    이름 유형 설명
    명명된 eventName 문자열 추가할 이벤트의 이름입니다.
    속성 포함 배열 옵션입니다. 이벤트에 대한 사용자 지정 속성 키-값 쌍입니다. 속성 키에는 점('.') 또는 달러('$') 기호를 사용할 수 없습니다. 그들은 잘릴 것입니다.
    지원되는 값 유형:
    • 날짜
    • NSNull
    • NSNumber
    • 문자열
    • URL
    주:
    , 속성 키 및 값의 총 크기는 eventName이벤트당 300바이트를 초과할 수 없습니다. 문자열은 UTF-8로 인코딩됩니다. 이 제한을 초과하는 이벤트는 무시됩니다.
    표 3. 반환
    유형 설명
    없음

    다음 예제에서는 속성이 있는 "Successful Login" 이벤트 및 "Open Case" 이벤트를 추가하는 방법을 보여줍니다.

    // Add event with properties
NowAnalytics.sharedAnalyticsService.addEvent(
  named: "Open Case", with: ["Screen Name": "Case",
                             "Case Number": "123",
                             "Case Priority": 5
])

    NowAnalyticsService - addScreenAction(named actionName: String)

    현재 화면에 사용자 지정 작업을 추가합니다. 이러한 작업은 세션 데이터의 일부로 사용자 대시보드에 표시되며 애플리케이션의 화면 변경을 설명합니다.

    표 4. 매개변수
    이름 유형 설명
    명명된 actionName 문자열 화면에 추가할 작업의 이름(예: MyButtonClick)입니다.

    최대 길이: 256 UTF-8 바이트
    표 5. 반환
    유형 설명
    없음 

    // Add event
NowAnalytics.sharedAnalyticsService.addEvent(named: "Successful Login")

    NowAnalyticsService - appendToUserProperty(named propertyName: String, listItem: String)

    지정된 항목을 지정된 사용자 속성 목록에 추가합니다 .

    표 6. 매개변수
    이름 유형 설명
    명명된 PropertyName 문자열 추가할 listItem 사용자 속성 목록의 이름입니다.
    목록 항목 문자열 속성에 추가할 목록 항목입니다.
    표 7. 반환
    유형 설명
    없음 

    // Append handled case to list
NowAnalytics.sharedAnalyticsService.appendToUserProperty(named: "Case Identifiers", listItem: "TASK-1")

    NowAnalyticsService - deleteCurrentUserData(completion: @escaping ((_ success: Bool) -> Void))

    현재 사용자와 연결된 모든 분석 데이터를 삭제합니다. 또한 이 메서드는 현재 활성 사용자를 설정 해제하고 이 디바이스를 향후 추적에서 옵트아웃합니다.

    현재 사용자를 설정하려면 setUserId() 메서드를 사용합니다.

    표 8. 매개변수
    이름 유형 설명
    완료 @escaping ((_ 성공 : 부울) -> 무효) 분석 데이터가 삭제된 후 실행할 완성 핸들러입니다.
    완료 처리기에 대한 값 반환:
    • 성공: 부울 값 true를 반환합니다.
    • 실패: 무효 - 연결이 없을 때처럼 서버에 연결할 수 없는 경우 사용자 경험 분석 오류가 발생할 수 있습니다. 실패하면 메서드를 다시 시도합니다.
    표 9. 반환
    유형 설명
    없음 

    // Delete user data
NowAnalytics.sharedAnalyticsService.deleteCurrentUserData(completion: { (success) -> Void in
  if success {
    // deletion succeeded
  } else {
    // deletion failed
  }
})

    NowAnalyticsService - incUserProperty(named propertyName: String, by value: Int)

    지정된 숫자 속성의 값을 지정된 값만큼 늘리거나 줄입니다.

    표 10. 매개변수
    이름 유형 설명
    명명된 PropertyName 문자열 증가시킬 사용자 속성의 이름입니다.
    값별 정수 속성을 증가시키는 값입니다. 음수 값을 입력하여 값을 감소시킵니다.
    표 11. 반환
    유형 설명
    없음 

    // Increment the "Cases Handled" count
NowAnalytics.sharedAnalyticsService.incUserProperty(named: "Cases Handled", by: 2)

    NowAnalyticsService - installJavascriptInterface(webView: WKWebView로)

    JavaScript를 사용하여 WebView 내에서 SNAnalytics() API의 메서드를 호출할 수 있도록 합니다.

    이 메서드는 네이티브 메서드를 노출하는 JavaScript에서 사용할 수 있는 SNMobileAnalytics 개체를 반환합니다.

    표 12. 매개변수
    이름 유형 설명
    웹뷰 WKWebView JavaScript 인터페이스를 삽입할 웹 뷰 객체입니다.
    표 13. 반환
    유형 설명
    객체 SNMobileAnalytics 

    // Register JS object inside the web page
// This will create an object named 'SNMobileAnalytics' on JS that will have the following methods:
// SNMobileAnalytics.setUserId(userId)                  example: SNMobileAnalytics.setUserId("John Doe")
// SNMobileAnalytics.startScreen(screenName)            example: SNMobileAnalytics.startScreen("WelcomeScreen")
// SNMobileAnalytics.addScreenAction(actionName)        example: SNMobileAnalytics.addScreenAction("MyButtonClick")
// SNMobileAnalytics.addEvent(eventName, properties)    example: SNMobileAnalytics.addEvent("Successful Login")
//                                                               SNMobileAnalytics.addEvent("Successful Login", JSON.stringify({"Screen Name": "Case", "Case Number": "123", "Case Priority": 5}))
NowAnalytics.sharedAnalyticsService.installJavascriptInterface(into: webView)

    NowAnalyticsService - removeUserProperty(명명된 propertyName: String)

    현재 사용자에 대해 지정된 속성을 삭제합니다.

    현재 사용자를 설정하려면 setUserId() 메서드를 사용합니다.

    표 14. 매개변수
    이름 유형 설명
    명명된 PropertyName 문자열 삭제할 사용자 속성의 이름입니다.
    표 15. 반환
    유형 설명
    없음 

    // Remove unnecessary property
NowAnalytics.sharedAnalyticsService.removeUserProperty(named: "Temp Cases")

    NowAnalyticsService - setDelegate(_ delegate: NowAnalyticsServiceDelegate?)

    알림을 받을 대리인에 대한 약한 참조를 설정합니다.

    표 16. 매개변수
    이름 유형 설명
    위임 NowAnalyticsServiceDelegate 옵션입니다. 대리자 클래스에 대한 참조가 포함된 개체입니다.
    // Register delegate
private var analyticsDelegate = NowAnalyticsDelegate()  // Keep ref of delegate
NowAnalytics.sharedAnalyticsService.setDelegate(analyticsDelegate)
    표 17. 반환
    유형 설명
    없음

    이 예시에서는 NowAnalyticsServiceDelegate에 대한 대리자 클래스를 정의하는 방법을 보여줍니다.

    // Define a delegate class for NowAnalyticsServiceDelegate
class NowAnalyticsDelegate: NowAnalytics.NowAnalyticsServiceDelegate {
  func nowAnalyticsSessionShouldStart() -> Bool {
    // Session is about to start, return true to allow session to start
    return true
  }

  func nowAnalyticsSessionDidStart(_ sessionId: String) {
    // Session was started
  }

  func nowAnalyticsSessionShouldEnd(_ sessionId: String) -> Bool {
    // Session is about to end, return true to allow session to end
    return true
  }

  func nowAnalyticsSessionDidEnd(_ sessionId: String) {
    // Session was ended
  }

  func nowAnalyticsDidDetectScreen(_ screenName: String) -> String? {
    // Example of skipping specific screen detection
    if (screenName == "LoginViewController") {
      return nil
    }

    // Example of appending a prefix for every screen detected
    return "MyApp_" + screenName
  }
}

// Register delegate
private var analyticsDelegate = NowAnalyticsDelegate()  // Keep ref of delegate
NowAnalytics.sharedAnalyticsService.setDelegate(analyticsDelegate)

    NowAnalyticsService - setUserId(_ userId: 문자열?)

    현재 사용자에 대한 애플리케이션의 사용자 ID를 설정합니다. nil을 전달하여 현재 사용자를 로그아웃합니다.

    표 18. 매개변수
    이름 유형 설명
    userID 문자열 옵션입니다. 애플리케이션별 사용자 식별자입니다.

    현재 사용자를 로그아웃하려면 nil을 전달합니다.

    사용자 ID에는 HTML 태그나 이름, 이메일 또는 전화번호와 같은 개인 데이터가 포함되어서는 안 됩니다.

    최대 길이: 256 UTF-8 바이트
    표 19. 반환
    유형 설명
    없음 

    // Add several properties at once
NowAnalytics.sharedAnalyticsService.setUserProperties([
  "Cases Handled": 100,
  "Last Login": Date(),
  "Is Remote": true,
  "Profile URL": URL(string: "https://www.servicenow.com")!
])

    NowAnalyticsService - setUserProperties(_ userProperties: [String: Any])

    현재 사용자에 대해 지정된 값으로 여러 속성을 설정합니다. 속성은 대시보드에서 사용자를 추적하려는 모든 것이 될 수 있습니다.

    이 함수를 호출하기 전에 setUserId() 함수를 호출해야 합니다.

    표 20. 매개변수
    이름 유형 설명
    userProperties 배열 설정할 사용자 속성의 키-값 쌍입니다.
    지원되는 값 유형:
    • NSNumber
    • 문자열
    • 날짜
    • URL
    • NSNull

    키에는 점(".") 또는 달러("$") 기호가 포함될 수 없습니다.

    최대 길이:
    • 키: 256자
    • 값: 1,000자
    표 21. 반환
    유형 설명
    없음 

    import NowAnalytics

// Initialize the Analytics SDK
NowAnalytics.configure(for: URL(string: "https://my.instance.service-now.com")!)

// Enable tracking consent
NowAnalytics.sharedAnalyticsService.trackingConsent = true

// Set User Id for proper identification
NowAnalytics.sharedAnalyticsService.setUserId("John Doe")

// Set the "Role" property of the user to "Admin"
NowAnalytics.sharedAnalyticsService.setUserProperty(named: "Role", with: "Admin")

// Add several properties at once
NowAnalytics.sharedAnalyticsService.setUserProperties([
    "Cases Handled": 100,
    "Last Login": Date(),
    "Is Remote": true,
    "Profile URL": URL(string: "https://www.servicenow.com")!
])

    NowAnalyticsService - setUserProperty(명명된 propertyName: 문자열, 값: 임의?)

    현재 사용자에 대해 지정된 속성을 지정된 값으로 설정합니다. 응용 프로그램에 적합한 모든 속성을 정의할 수 있습니다.

    이 함수를 호출하기 전에 setUserId() 함수를 호출해야 합니다.

    표 22. 매개변수
    이름 유형 설명
    명명된 PropertyName 문자열 설정할 사용자 속성의 이름입니다. 점('.') 또는 달러('$') 기호는 포함할 수 없습니다.

    최대 길이: 256자
    값 포함 모두 사용자 속성을 설정할 값입니다.
    지원되는 값 유형:
    • 날짜
    • NSNull
    • NSNumber
    • 문자열
    • URL

    최대 길이: 1,000자
    표 23. 반환
    유형 설명
    없음 

    // Set the "Role" property of the user to "Admin"
NowAnalytics.sharedAnalyticsService.setUserProperty(named: "Role", with: "Admin")

    NowAnalyticsService - startScreen(명명된 screenName: 문자열)

    연결된 화면이 UI에 처음 나타나는 시간을 기록합니다.

    viewDidAppear(_:) 메서드 뒤에 이 메서드를 호출합니다.

    표 24. 매개변수
    이름 유형 설명
    명명된 screenName 문자열 시작 시간을 기록할 화면의 이름입니다(예: WelcomeScreen ). 이는 분석 대시보드에서 화면 및 표시/집계로 정의하려는 모든 것이 될 수 있습니다.

    최대 길이: 256 UTF-8 바이트
    표 25. 반환
    유형 설명
    없음 

    // Mark the appearance starting time of a screen
// This method should be usually called from the viewDidAppear
NowAnalytics.sharedAnalyticsService.startScreen(named: "WelcomeScreen")