{"id":28586023,"url":"https://github.com/aws-solutions/clickstream-analytics-on-aws-swift-sdk","last_synced_at":"2026-01-18T01:18:12.734Z","repository":{"id":166687359,"uuid":"633721767","full_name":"aws-solutions/clickstream-analytics-on-aws-swift-sdk","owner":"aws-solutions","description":"Swift SDK for Clickstream Analytics on AWS","archived":false,"fork":false,"pushed_at":"2025-02-06T00:46:43.000Z","size":643,"stargazers_count":15,"open_issues_count":0,"forks_count":1,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-02-06T01:28:34.772Z","etag":null,"topics":["analytics","aws","aws-clickstream-solution","aws-solutions","clickstream","ios","sdk-swift"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/solutions/implementations/clickstream-analytics-on-aws/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-28T06:15:13.000Z","updated_at":"2025-02-03T17:50:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"b816645c-d623-4593-a87f-23b3e9137e5b","html_url":"https://github.com/aws-solutions/clickstream-analytics-on-aws-swift-sdk","commit_stats":null,"previous_names":["awslabs/clickstream-swift","aws-solutions/clickstream-analytics-on-aws-swift-sdk"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-swift-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-swift-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-swift-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-swift-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-solutions","download_url":"https://codeload.github.com/aws-solutions/clickstream-analytics-on-aws-swift-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-swift-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259214187,"owners_count":22822841,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","aws","aws-clickstream-solution","aws-solutions","clickstream","ios","sdk-swift"],"created_at":"2025-06-11T06:30:28.735Z","updated_at":"2026-01-18T01:18:12.708Z","avatar_url":"https://github.com/aws-solutions.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Solution Clickstream Analytics SDK for Swift\n\n## Introduction\n\nClickstream Swift SDK can help you easily collect and report in-app events from iOS devices to AWS. This SDK is part of an AWS solution - [Clickstream Analytics on AWS](https://github.com/aws-solutions/clickstream-analytics-on-aws), which provisions data pipeline to ingest and process event data into AWS services such as S3, Redshift.\n\nThe SDK relies on the Amplify for Swift Core Library and is developed according to the Amplify Swift SDK plug-in specification. In addition, we've added features that automatically collect common user events and attributes (e.g., screen view, first open) to simplify data collection for users.\n\nVisit our [Documentation site](https://aws-solutions.github.io/clickstream-analytics-on-aws/en/latest/sdk-manual/swift/) and to learn more about Clickstream Swift SDK.\n\n### Platform Support\n    \nThe Clickstream SDK supports iOS 13+.\n\n[**API Documentation**](https://aws-solutions.github.io/clickstream-analytics-on-aws-swift-sdk/) \n\n- [Objective-C API Reference](https://aws-solutions.github.io/clickstream-analytics-on-aws-swift-sdk/Classes/ClickstreamObjc.html)\n\n## Integrate SDK\n\nClickstream requires Xcode 13.4 or higher to build.\n\n### 1.Add Package\n\nWe use **Swift Package Manager** to distribute Clickstream Swift SDK, open your project in Xcode and select **File \u003e Add Packages**.\n\n![](images/add_package.png)\n\nEnter the Clickstream Library for Swift GitHub repo URL (`https://github.com/aws-solutions/clickstream-swift`) into the search bar, you'll see the Clickstream Library for Swift repository rules for which version of Clickstream you want Swift Package Manager to install. Choose **Up to Next Major Version**, then click **Add Package**, make the Clickstream product checked as default, and click **Add Package** again.\n\n![](images/add_package_url.png)\n\n### 2.Parameter configuration\n\nDownlod your `amplifyconfiguration.json` file from your Clickstream solution control plane, and paste it to your project root folder:\n\n![](images/add_amplify_config_json_file.png)\n\nthe json file will be as follows:\n\n```json\n{\n  \"analytics\": {\n    \"plugins\": {\n      \"awsClickstreamPlugin \": {\n        \"appId\": \"appId\",\n        \"endpoint\": \"https://example.com/collect\",\n        \"isCompressEvents\": true,\n        \"autoFlushEventsInterval\": 10000,\n        \"isTrackAppExceptionEvents\": false\n      }\n    }\n  }\n}\n```\n\nYour `appId` and `endpoint` are already set up in it, here's an explanation of each property:\n\n- **appId**: the app id of your project in control plane.\n- **endpoint**: the endpoint url you will upload the event to AWS server.\n- **isCompressEvents**: whether to compress event content when uploading events, default is `true`\n- **autoFlushEventsInterval**: event sending interval, the default is `10s`\n- **isTrackAppExceptionEvents**: whether auto track exception event in app, default is `false`\n\n### 3.Initialize the SDK\n\nOnce you have configured the parameters, you need to initialize it in your app delegate's `application(_:didFinishLaunchingWithOptions:)` lifecycle method:\n\n#### 3.1 Initialize the SDK with default configuration\n```swift\nimport Clickstream\n...\nfunc application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -\u003e Bool {\n    do {\n        try ClickstreamAnalytics.initSDK()\n    } catch {\n        assertionFailure(\"Fail to initialize ClickstreamAnalytics: \\(error)\")\n    }\n    return true\n}\n```\n\n#### 3.2 Initialize the SDK with global attributes and custom configuration\n\nThe following example code shows how to add traffic source fields as global attributes when initializing the SDK.\n\n```swift\nimport Clickstream\n...\nfunc application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -\u003e Bool {\n    do {\n        let configuration = ClickstreamConfiguration()\n            .withAppId(\"your appId\")\n            .withEndpoint(\"https://example.com/collect\")\n            .withLogEvents(true)\n            .withInitialGlobalAttributes([\n                ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_SOURCE: \"amazon\",\n                ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_MEDIUM: \"cpc\",\n                ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CAMPAIGN: \"summer_promotion\",\n                ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CAMPAIGN_ID: \"summer_promotion_01\",\n                ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_TERM: \"running_shoes\",\n                ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CONTENT: \"banner_ad_1\",\n                ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CLID: \"amazon_ad_123\",\n                ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CLID_PLATFORM: \"amazon_ads\",\n                ClickstreamAnalytics.Attr.APP_INSTALL_CHANNEL: \"App Store\"\n            ])\n        try ClickstreamAnalytics.initSDK(configuration)\n    } catch {\n        assertionFailure(\"Fail to initialize ClickstreamAnalytics: \\(error)\")\n    }\n    return true\n}\n```\n\nBy default, we will use the configurations in `amplifyconfiguration.json` file. If you add a custom configuration, the added configuration items will override the default values. \n\nYou can also add all the configuration parameters you need in the `initSDK` method without using the `amplifyconfiguration.json` file.\n\n#### 3.3 SwiftUI configuration\nIf your project is developed with SwiftUI, you need to create an application delegate and attach it to your `App` through `UIApplicationDelegateAdaptor`. \n\n```swift\n@main\nstruct YourApp: App {\n    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate\n    var body: some Scene {\n        WindowGroup {\n            YourView()\n        }\n    }\n}\n```\n\nClickstream Swift SDK depends on method swizzling to automatically record screen views. SwiftUI apps must [record screen view events manually](#record-screen-view-events-manually), and disable automatic tracking of screen view events by setting `configuration.withTrackScreenViewEvents(false)` when the SDK is initialized.\n\n### 4. Update Configuration\n\n```swift\nimport Clickstream\n\n// configure the sdk after initialize.\ndo {\n    let configuration = try ClickstreamAnalytics.getClickstreamConfiguration()\n    configuration.withAppId(\"your appId\")\n        .withEndpoint(\"https://example.com/collect\")\n        .withLogEvents(true)\n        .withCompressEvents(true)\n        .withSessionTimeoutDuration(1800000)\n        .withTrackAppExceptionEvents(true)\n        .withTrackScreenViewEvents(true)\n        .withTrackUserEngagementEvents(true)\n} catch {\n    print(\"Failed to config ClickstreamAnalytics: \\(error)\")\n}\n```\n\n\u003e note: this configuation will override the default configuation in `amplifyconfiguration.json` file\n\n### Start using\n\n#### Recored event.\n\nAdd the following code where you need to complete the event report.\n\n```swift\nimport Clickstream\n\nlet attributes: ClickstreamAttribute = [\n    \"Channel\": \"apple\",\n    \"Successful\": true,\n    \"ProcessDuration\": 12.33,\n    \"UserAge\": 20,\n]\nClickstreamAnalytics.recordEvent(\"testEvent\", attributes)\n\n// for record an event with event name\nClickstreamAnalytics.recordEvent(\"button_click\")\n```\n\n#### Record event with items\n\nYou can add the following code to log an event with an item.\n\n**Note: Only pipelines from version 1.1+ can handle items with custom attribute.**\n\n```swift\nimport Clickstream\n\nlet attributes: ClickstreamAttribute = [\n    ClickstreamAnalytics.Item.ITEM_ID: \"123\",\n    ClickstreamAnalytics.Item.CURRENCY: \"USD\",\n    \"event_category\": \"recommended\"\n]\n\nlet item_book: ClickstreamAttribute = [\n    ClickstreamAnalytics.Item.ITEM_ID: 123,\n    ClickstreamAnalytics.Item.ITEM_NAME: \"Nature\",\n    ClickstreamAnalytics.Item.ITEM_CATEGORY: \"book\",\n    ClickstreamAnalytics.Item.PRICE: 99.9,\n    \"book_publisher\": \"Nature Research\"\n]\nClickstreamAnalytics.recordEvent(\"view_item\", attributes, [item_book])\n```\n\n#### Record Screen View events manually\n\nBy default, SDK will automatically track the preset `_screen_view` event when ViewController triggers `viewDidAppear`.\n\nYou can also manually record screen view events whether or not automatic screen view tracking is enabled, add the following code to record a screen view event with two attributes.\n\n* `SCREEN_NAME` Required. Your screen's name.\n* `SCREEN_UNIQUE_ID` Optional. Set the hashValue of your ViewController or UIView. If you do not set, SDK will set a default value based on the current ViewController's hashValue.\n\n```swift\nimport Clickstream\n\nClickstreamAnalytics.recordEvent(ClickstreamAnalytics.EventName.SCREEN_VIEW, [\n    ClickstreamAnalytics.Attr.SCREEN_NAME: \"HomeView\",\n    ClickstreamAnalytics.Attr.SCREEN_UNIQUE_ID: homeView.hashValue\n])\n```\n\n#### Add global attribute\n\n```swift\nimport Clickstream\n\nlet globalAttribute: ClickstreamAttribute = [\n    ClickstreamAnalytics.Attr.APP_INSTALL_CHANNEL: \"apple\",\n    \"class\": 6,\n    \"level\": 5.1,\n    \"isOpenNotification\": true,\n]\nClickstreamAnalytics.addGlobalAttributes(globalAttribute)\n\n// for delete an global attribute\nClickstreamAnalytics.deleteGlobalAttributes(\"level\")\n```\n\n#### Login and logout\n\n```swift\nimport Clickstream\n\n// when user login usccess.\nClickstreamAnalytics.setUserId(\"userId\")\n\n// when user logout\nClickstreamAnalytics.setUserId(nil)\n```\n\nWhen we log into another user, we will clear the before user's user attributes, after `setUserId()` you need to add new user's attribute.\n\n#### Add user attribute\n\n```swift\nimport Clickstream\n\nlet userAttributes : ClickstreamAttribute=[\n    \"_user_age\": 21,\n    \"_user_name\": \"carl\"\n]\nClickstreamAnalytics.addUserAttributes(userAttributes)\n```\n\nCurrent login user‘s attributes will be cached in disk, so the next time app launch you don't need to set all user's attribute again, of course you can update the current user's attribute when it changes.\n\n#### Log the event json in debug mode\n\n```swift\nimport Clickstream\n\n// log the event in debug mode.\ndo {\n    var configuration = try ClickstreamAnalytics.getClickstreamConfiguration()\n    configuration.isLogEvents = true\n} catch {\n    print(\"Failed to config ClickstreamAnalytics: \\(error)\")\n}\n```\n\nAfter config `configuration.isLogEvents = true` and when you record an event, you can see the event json at your Xcode log pannel by filter `EventRecorder`.\n\n#### Send event immediately\n\n```swift\nimport Clickstream\n// for send event immediately.\nClickstreamAnalytics.flushEvents()\n```\n\n#### Disable SDK\n\nYou can disable the SDK in the scenario you need. After disabling the SDK, the SDK will not handle the logging and sending of any events. Of course you can enable the SDK when you need to continue logging events.\n\n```swift\nimport Clickstream\n\n// disable SDK\nClickstreamAnalytics.disable()\n\n// enable SDK\nClickstreamAnalytics.enable()\n```\n\n## How to build \u0026 test locally\n\n### Config your code format\n\nInstall [swiftformat plugin](https://github.com/nicklockwood/SwiftFormat#xcode-source-editor-extension) in your Xcode, and config shortcut for code format.\n\n### Config your code lint\n\nInstall [swiftlint](https://github.com/realm/SwiftLint), and execute the below command at the project root folder:\n\n```bash\nswiftlint\n```\n\n### Build\n\nOpen an termial window, at the root project folder to execute: \n\n```bash\nswift build\n```\n\n### Test\n\n```bash\nswift test\n```\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis library is licensed under [Apache 2.0 License](./LICENSE).\n\n## Anonymous operational metrics\n\nThis solution collects anonymous operational metrics to help AWS improve the quality and features of the solution. For more information, including how to disable this capability, please see the [implementation guide](https://docs.aws.amazon.com/solutions/latest/clickstream-analytics-on-aws/solution-overview.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-swift-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-swift-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-swift-sdk/lists"}