adobe / aepsdk-core-ios Goto Github PK

Adobe Experience Platform Mobile Core SDK in Swift

License: Apache License 2.0

Objective-C 0.66% Swift 97.61% Makefile 0.79% Ruby 0.31% Shell 0.64%

aepsdk-core-ios's Introduction

Adobe Experience Platform Core SDK

About this project

The AEPCore, AEPServices, and AEPIdentity extensions represent the foundation of the Adobe Experience Platform SDK - every app using the SDK must include them. These modules contain a common set of functionality and services which are required by all SDK extensions.

AEPCore contains implementation of the Event Hub. The Event Hub is the mechanism used for delivering events between the app and the SDK. The Event Hub is also used for sharing data between extensions.

AEPServices provides several reusable implementations needed for platform support, including networking, disk access, and database management.

AEPIdentity implements the integration with Adobe Experience Platform Identity services.

AEPSignal represents the Adobe Experience Platform SDK's Signal extension that allows marketers to send a "signal" to their apps to send data to external destinations or to open URLs.

AEPLifecycle represents the Adobe Experience Platform SDK's Lifecycle extension that helps collect application Lifecycle metrics such as, application install or upgrade information, application launch and session information, device information, and any additional context data provided by the application developer.

Requirements

Xcode 15 (or newer)
Swift 5.1 (or newer)

Installation

These are currently the supported installation options:

CocoaPods

# Podfile
use_frameworks!

# for app development, include all the following pods
target 'YOUR_TARGET_NAME' do
    pod 'AEPCore'
    pod 'AEPLifecycle'
    pod 'AEPIdentity'
    pod 'AEPSignal'
end

# for extension development, include AEPCore and its dependencies
target 'YOUR_TARGET_NAME' do
    pod 'AEPCore'
end

Replace YOUR_TARGET_NAME and then, in the Podfile directory, type:

$ pod install

Swift Package Manager

To add the AEPCore Package to your application, from the Xcode menu select:

File > Swift Packages > Add Package Dependency...

Enter the URL for the AEPCore package repository: https://github.com/adobe/aepsdk-core-ios.git.

When prompted, input a specific version or a range of versions, and choose all the AEP* libraries.

Alternatively, if your project has a Package.swift file, you can add AEPCore directly to your dependencies:

dependencies: [
    .package(url: "https://github.com/adobe/aepsdk-core-ios.git", .upToNextMajor(from: "5.0.0"))
]

Project Reference

Include AEPCore.xcodeproj in the targeted Xcode project and link all necessary libraries to your app target.

Binaries

Run make archive or make archive-ios from the root directory to generate .xcframeworks for each module. The make archive command will generate XCFrameworks which support iOS and tvOS, while make archive-ios will generate XCFrameworks for iOS alone. Once complete, the XCFrameworks can be found in the build folder. Drag and drop all .xcframeworks to your app target in Xcode.

Documentation

Additional documentation for usage and SDK architecture can be found under the Documentation directory.

Related Projects

Project	Latest Release	Github
Rules Engine		Link
Profile		Link
Adobe Experience Platform Edge Network		Link
Identity for Edge Network		Link
Consent for Edge Network		Link
Edge Bridge		Link
Adobe Experience Platform Assurance		Link
Places Service		Link
Adobe Analytics		Link
Adobe Streaming Media for Edge Network		Link
Adobe Analytics - Media Analytics for Audio & Video		Link
Adobe Audience Manager		Link
Adobe Journey Optimizer		Link
Adobe Journey Optimizer - Decisioning		Link
Adobe Target		Link
Adobe Campaign Standard		Link
Adobe Campaign Classic		Link
AEP SDK Sample App for iOS	-	Link

Contributing

Contributions are welcomed! Read the Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.

aepsdk-core-ios's People

Stargazers

Watchers

aepsdk-core-ios's Issues

Epic: 3rd party extensions compatibility

Implement APIs that are compatible with current 3rd party extensions
Get one of the 3rd party extensions working with swift Core (griffon, mobile services, places, or any extension extension)

Epic: Event hub

Register listeners
Register extensions and creating extensions
Updating and getting shared state
Dispatching an event
Timeout control on response listeners
Error callbacks on response listeners
Shared state of Extension details
Owner of operation orderer

Epic: Security

Work with Security team
Setup auto security scan?

Epic: Project Structure

Design the project structure that (1) Simple and clean (2) easy to be included by another project (3) Easy for us to define the contract of Core
Utilities. What should we expose?
Configuration/Identity/Lifecycle/Signal/platform services in separate target vs separate project?
For platform services, make it easy for other teams to contribute
watchos/tvos structure(optional)

Epic : Distribution of Core SDK

First step: Source code + Pods + Makefile
Binaries? Static lib vs xcframework
How to distribute Rules Engine code with Core
SPM
Carthage

implement Peek N and Remove N in DataQueue

From discussion #26 (comment)

Decided to provide Peek and Remove APIs for now, and implement Peek N and Remove N in a separate task that would be required for the Platform extension once ExEdge batching is enabled by default – pending implementation of ExEdge request size restrictions.

Payment required

🚨 Reminder! Less than one month left to migrate your repositories over to Snyk before Greenkeeper says goodbye on June 3rd! 💜 🚚💨 💚

Find out how to migrate to Snyk at greenkeeper.io

🚨 You privatised your repo. 🚨

Hello!
You have set your repository to private. From now on Greenkeeper is no longer free. We have disabled your repo for now.
Please enter your payment information at account.greenkeeper.io.
For pricing information, please visit https://greenkeeper.io/#pricing.

Epic: Platform Services

Epic: CI/CD

Use CircleCI before the repo is public
Makefile
CI/CD tools.
Split CircleCI jobs (build-and-test, codecov) and add branch protection rules on main branch for both jobs, on dev branch for build-and-test only
Release automation
Git hub actions.

Add Logs to EventHub

part of #77

Discussion: Timeout for async APIs with return values

Discussion: who should own the OperationOrderer

In the current implementation, extension owns the OperationOrderer and add/fetch the event from the queue. It is flexible, so Edge extension can even use two queues.
https://github.com/adobe/aepsdk-platform-ios/blob/dev/code/src/ExperiencePlatformInternal.swift
https://github.com/adobe/aepsdk-core-ios/blob/68d111fd73d4e68da62c203cdd779ff4a53b2c11/Sources/configuration/AEPConfiguration.swift

Another option is that eventhub owns all the queues, so the extension doesn't need to care about it. Once an extension receives an event, it is ready to be processed. Potentially if we want to make it more flexible, eventhub can also assign multiple queues for an extension, and if we allow the extension passing in a groupname when registering a listener.

Json Rule parser

Define a class that conforms to Rule and meet our reqiuremnt for consquence
Pasre the launch rules json to Rule

Epic: Integration with Rules Engine

Integrate Eventhub with Rules Engine (estimate: 1 weeks) #95
Consequence handling
- Event (estimate: 1/2 week) #97
- Data modification (attach, modify, delete) (estimate: 2 weeks) #85
Json Rule parser (estimate: 1 week) #96
Launch Rule download (estimate: 1 week) #94
Token replacement (estimate: 1 week) #92
First launch support (estimate: 1 week) #98

Style Guide

Define Style Guide
Discuss with team

Reference:
https://swift.org/documentation/api-design-guidelines/
https://github.com/raywenderlich/swift-style-guide
https://google.github.io/swift/

"DataQueue Service" Interface Design

Scope
The scope of this document is to prototype the interface of the database service in Swift MobileCore.

Requirement
The database service provided in MobileCore is used to persistent objects to the SQLite database, this feature mainly used by Identity/ Platform/ Analytics extensions(Swift).

Details

Table schema
- id TEXT
- timestamp INTEGER
- data TEXT
Support using multiple DataQueue instances in mobile SDK, the "Data Queue" and the database are one-to-one correspondence.
UUID/Timestamp can reuse the values in the Event object

Sample Code

The following code shows the database service interface and some of the sample code demonstrate the usage of the database service.

CLICK ME

enum DatabaseError: Error {
    case Unknown
}

public class DataQueueService{
    public static var shared = DataQueueService()
    private var queues: [String: DataQueue] = [:]
    private init(){ }
    public func initDataQueue(databaseName: String, databaseFilePath: FileManager.SearchPathDirectory = .documentDirectory) -> Result<DataQueue, Error>{
        // create new DB if not exist; return cached dataQueue if exist
        return .failure(DatabaseError.Unknown)
    }
    public func deleteDatabase(databaseName: String) -> Result<Bool, Error>{
        return .failure(DatabaseError.Unknown)
    }
    public func closeDatabase(databaseName: String) -> Result<Bool, Error>{
        return .failure(DatabaseError.Unknown)
    }
}

public protocol DataQueue {
    var databaseName: String { get set }
    var databaseFilePath: FileManager.SearchPathDirectory { get set }
    
    func save(dataEntity: DataEntity) -> Result<String, Error>
    func delete(_ byCondition: Condition) -> Result<Bool, Error>
    func load(_ byCondition: Condition) -> Result<[DataEntity], Error>
    // func pop(_ byCondition: Condition) -> Result<[DataEntity], Error>
}


public enum Condition {
    case last(_ number: Int = 1)
    case first(_ number: Int = 1)
    case since(timestamp: NSDate)
    case before(timestamp: NSDate)
    case UUID(_ id: UUID)
    case all
}


public protocol DataEntity{
    var timestamp: Date { get set }
    var uuid: UUID { get set }
    var data: Data { get set }
    init(uuid: UUID, timestamp: Date, data: Data)
}

struct Event: Codable {
    var id: UUID
    var timestamp: Date
}

class PlatformHit: DataEntity {
    var timestamp: Date
    var uuid: UUID
    var data: Data
    required init(uuid: UUID, timestamp: Date, data: Data) {
        self.uuid = uuid
        self.timestamp = timestamp
        self.data = data
    }
}

let dataQueue = DataQueueService.shared.initDataQueue(databaseName: "aep_platform_db_1")
let event = Event(id: UUID(), timestamp: Date())
let eventData = try JSONEncoder().encode(event)
let hit = PlatformHit(uuid: event.id, timestamp: event.timestamp, data: eventData)
 
try dataQueue.get().save(dataEntity: hit)

Epic: Implement Configuration Extension

(GetIdentities) Listen and handle Configuration request identity events
Implement environment aware configuration

Epic: Lifecycle extension

Lifecycle

lifecycleStart
#781
Lifecycle Functional Tests

Implement Unzipping service

Feature Scoping

EventHub

Register listeners
Register extensions and creating extensions
Updating and getting shared state
Dispatching an event
Timeout control on response listeners
Error callbacks on response listeners
Shared state of Extension details

Rules

Standalone Rule Engine (WIP, estimate: 2 weeks)
Integrate Eventhub with Rules Engine (estimate: 1 weeks)
Consequence handling
- Event (estimate: 1/2 week)
- Data modification (attach, modify, delete) (estimate: 2 weeks)
Json rules parser (estimate: 1 week)
Launch Rule download (estimate: 1 week)
Token replacement (estimate: 1 week)
First launch support (estimate: 1 week)

Configuration

Identity (estimate: 3 weeks)

Lifecycle

lifecycleStart
lifecyclePause
Lifecycle Functional Tests

Signal

Postback (estimate: 1/2 week)
OpenURL (estimate: 1/2 week)

Platform services

Migration

v4 to swift (estimate 1-2 weeks)
v5 to swift (estimate: 1-2 weeks, will need lots of testing to ensure backward compatibility and possibly providing some shim layers).

Requirement from Edge and Messaging

Edge
- core + rules (don't need data modification consequence at this moment)
- utils
- database
Messaging
- TBD

Epic: Compatibility with Obj-C

Make all public APIs Obj-C compatible:
- Core
- Configuration
- Lifecycle
- Identity
Allow Objective-C extensions to be developed
Decide if platform services should be compatible with Obj-C
Draft the guidelines on the best practices for handling compatibility issues

"DataQueueService" improvement

If you have any questions or suggestions for DataQueueService, please leave feedback on this page.

It would be good to smoke test it in a demo app and make sure the access is correct. (from @emdobrin )

First launch rule support

Investigate the solutions

Epic: Implement Identity Extension

Investigation : Cocoapods

Investigate: error handling across swift and obj-c

part of #35

throw Error

Xcode will handle the translation, it will do two things:
- Add an extra parameter taking a nullable pointer to NSError*.
- Change the return type to Optional, if the return type is Void, it is changed to BOOL.
Returns a Result (https://developer.apple.com/documentation/swift/result)
- Not supported
Creates a class as the return type ->

public class Result: NSObject {
    public let isSuccessful: Bool
    public let error:AEPError
    //...
}

Support for data attach/modify/delete consequence

Event data merge

Part of #54

Discussion: Integrate Rules Engine with Eventhub

We have two options:

Eventhub owns a rule engine and provides an internal API for Configuration extension inject rules. And also need to provides the capability to reprocess the events, to support the first launch rules scenario.
Event preprocessor. Similar to the preprocessor concept we have in v5(which was never used), eventhub provides an internal API for Configuration (or RulesEngine extension) to register an event preprocessor, which will be called before the events being distributed to each extension container. So configuration will own the rules engine. And following this idea, Configuration can cache the first several events before rules are loaded and re-evaluate the events later with its own rules engine. I think this can be easily achieved by having a flag, which can switch Configuration from caching events mode to preprocessor mode.

Rules consequence handling: new Events

Implement token replacement in Rules Engine

Subtask of <Epic: Integration with Rules Engine> #54

Add logs

Add logs to the existing code once the logging service is ready.

Should follow the same rule as in v5 SDK

In the SDK there are four different types of logging that we will output to the developer's console. Their intended usage is outlined below:

Log.trace - This method should be used to deliver highly detailed information to the console. Information provided to the trace method is verbose and should give insight to the developer about how the SDK is processing data. The intended audience for trace logs is an Adobe SDK team member. trace logs will only be printed to the console if the developer has set a LoggingMode of VERBOSE in the SDK.
Log.debug - This method should be used when printing high-level information to the console about the data being processed. The intended audience for debug logs is a developer integrating the SDK. debug logs will be printed to the console if the developer has set a LoggingMode of VERBOSE or DEBUG in the SDK.
Log.warning - This method should be used to indicate that a request has been made to the SDK, but the SDK will be unable to perform the requested task. An example of when to use warning is when catching an unexpected but recoverable exception and printing its message. The intended audience for warning logs is a developer integrating the SDK. warning logs will be printed to the console if the developer has set a LoggingMode of VERBOSE, DEBUG, or WARNING in the SDK.
Log.error - This method should be used when the SDK has determined that there is an unrecoverable error. The intended audience for error logs is a developer integrating the SDK. error logs are always enabled, and will be printed to the developer console regardless of the LoggingMode of the SDK.

Epic: Migration

v4 to swift (estimate 1-2 weeks) #216
v5 to swift (estimate: 1-2 weeks, will need lots of testing to ensure backward compatibility and possibly providing some shim layers). #217

Alpha Release Scoping

Feature Scope
#12

Test strategy (WIP, estimate: 2 weeks)

Unit test
Functional test (Testable Extension runtime)
Performance test
Test harness? The current plan is Core will not share any testable.
Compatibility test (Hermetic test)? No
Compatibility test with Griffon?

Project Structure: (WIP, estimate: 0.5 weeks)

Design the project structure that (1) Simple and clean (2) easy to be included by another project (3) Easy for us to define the contract of Core
Utilities. What should we expose?
Configuration/Identity/Lifecycle/Signal/platform services in separate target vs separate project?
For platform services, make it easy for other teams to contribute
watchos/tvos structure(optional)

Distribution (WIP, estimate: 1 weeks)

others:

How to distribute Rules.
Investigate ABI stability issues.

Open Source:

Contribution workflow
Tickets management

CI/CD (estimate: 2 weeks)

Code style (estimate: 1 week)

Define code style

Sample App (estimate: 1 week)

Swift
Obj-c

Sample Extensions (estimate: 1 week)

Swift
Obj-c

Design docs (estimate: 2 weeks)

Eventhub design docs
Eventhub contract
Each extension design docs

Compatibility with Obj-C

Make the current code compatible with obj-c
Write up the guidelines

3rd party extensions compatibility

Implement APIs that are compatible with current 3rd party extensions
Get one of the 3rd party extensions working with swift Core
Documentation

V5 compatibility

Implement ACPCore layer as a wrapper
Get a sample app on v5 SDK to be working with new ACPCore pods
Documentation

Security (estimate: 1 week)

Work with Security team
Fix security issues
Setup auto security scan?

Size calculation

Manual Calculation

Post Alpha

Size calculation

Automation (estimate: 1 week)

Unity/RN/Flutter/Xamarin/Cordova plugins (estimate: 2 weeks)

Customer care training

** Involve 3rd party vendor**

Public Documentation (estimate: 2 weeks)

Figure out a release plan

when Beta
having customers try out

Discussion: Core contract

Problem to solve:

Define the contract of Core, especially Eventhub. Define how an extension works with eventhub. Easier to communicate with extensions only when the contract of Core changed.
Testing of an extension doesn't need to rely on implementation of eventhub, extension just needs to focus on testing its own logic. This will increase the stability of the test and the ease of maintain.

Currently, all the xtensions get the eventhub related methods from https://github.com/adobe/aepsdk-core-ios/blob/master/Sources/eventhub/Extension.swift#L35. With this implementation, there is no way to override those methods in tests. And Eventhub is a final class, so there is either no way to create a faked version of eventhub.

Options

Define EventHubProtocol. #24
Define open class ExtensionContext<T:Extension>, #23

Design : UI Services API

Design Logging service API

Add rules engine to configuration

Define preprocessor in Eventhub
Include rules engine as a dependency in Configuration
Configuration hold a rule engine instance
Implement a preprocessor to run rules

Investigation : SPM

Constraint:

Technically, one repo can only define one package.swift. You can define a package in a sub folder, but there is no way for another project to include it. If you define a package in a sub folder and reclaim the same module in the root package, it works, but when you open the project from the root package, xcdoe won't show the source code in the sub folder.
Couldn't run test that relies on Bundle
Doesn't support resources (until swift 5.3), https://github.com/apple/swift-evolution/blob/master/proposals/0271-package-manager-resources.md
Doesn't platform specific sources (until swift 5.3), https://github.com/apple/swift-evolution/blob/master/proposals/0273-swiftpm-conditional-target-dependencies.md

Investigation : xcframeworks

Design Cache service API

Epic: Implement Signal Extension

Epic: Sample App

Objc-C sample app
Swift sample app
Objc-C sample extension
Swift sample extension

Use prefixed keys instead of Suites in DataStore

Our current DataStore implementation uses suites for namespacing the stores when instead we should be using prefixed keys like in Obj-C.

Unzipper Utility Unit Tests and Performance Tests

Add unit test coverage for helper functions in the Unzipper utilities.
Add performance test coverage

Add Logs to Services module

part of #77

Investigation: Code format & lint tool

Requirements:

Auto correct source from pre-commit Git hook
Validate format in CI build step
Support minimum Swift version 5.1
Disable specific rules when correcting test source
(Optional) Xcode integration to display lint issues

Summary:

I've looked into the following tools:

Of the above requirements, all the tools except Google's swift-format support all requirements. I could not determine how to build and run Google's swift-format using the Swift 5.1 toolchain.

Below is a summary of each tool. For our use, following the above requirements, I would consider choosing either SwiftFormat if we do not need rules for documentation or Apple's swift-format for the documentation rules and if we don't mind building from source or including the binaries in source control.

Here is a comparison of those two tools when run against the AEP Experience Platform source using the default configurations.
SwiftFormat:
https://github.com/kevinlind/platform-extension-ios/pull/18/files
swift-format:
https://github.com/kevinlind/platform-extension-ios/pull/17/files
An interesting correction using swift-format was to ExperiencePlatformConstants.swft where it changed the structs to enums. However, I needed to run the tool four times for it to fully "correct" that file. It appears it didn't correctly detect all the nested structs in one pass.

SwiftFormat

SwiftFormat is a formatting focused tool and it can auto-correct all of its defined rules. It appears, however, that it achieves this by not defining rules for issues like documentation or variable names. The tool may be installed from CocoaPods or Homebrew which would allow us to reference it as a dependency instead of including a binary in GitHub.

Pros:
- Multiple ways to install the tool (CocoaPods, Homebrew, Mint, GitHub source)
- Appears to work independent of the installed Swift version (recommended to provide minimum supported Swift version to tool)
- Both auto correct and lint options
- Use of configuration files to enable/disable rules
- Xcode Integration with Build Phase run script
- CLI for Git hook and CI build step
- All rules were auto corrected (using default settings)
- Option to add/replace file header
Cons:
- No rules for documentation or variable names

apple/swift-format

Apple's swift-format is built from the GitHub source. We would either need to include the binary in Git or clone the repo and build the tool as a CI step. There are separate branches for building against Swift 5.1 and 5.2, so we'd need to determine the Swift version installed before building and running the tool. We can integrate with Xcode via a Build Phase Run Script which displays build warnings in the issue navigator, however I wasn't seeing source code highlighting like with the other tools. Not all the rules are correctable, but using a configuration file can disable specific rules when running a CI verification step. The non-correctable rules were mainly for missing documentation and variable name choice (i.e. LOG_TAG).

Pros:
- Both auto correct and lint options
- Use of configuration files to enable/disable rules
- CLI for Git hook and CI build step
- Xcode Integration with Build Phase run script
Cons:
- Only installs from Git source
- Must build different branches depending on system Swift toolchain
- Xcode integration does not highlight source code
- Like other solutions, auto format does not fix for all the rules. Though, most of the non corrected rules were documentation issues.
- Didn’t fully correct all the issues in one run (didn't catch nested structs)

google/swift/tree/format

This is Google's fork of Apple's swift-format. It is referenced in the Pitch: an Official Style Guide and Formatter for Swift. The documentation is similar to Apple's swift-format, but Google's swift-format does contain a couple more rules than Apple's. I wasn't able to fully evaluate this tool, however, as it doesn't build on Swift 5.1. It is unclear which tool, either Apple's or Google's, will be embraced by the Swift developer community.

SwiftLint

SwiftLint is developed by Realm and is designed more as a linting tool which also works as a formatter (as opposed to SwiftFormat which works primarily as a formatting tool). There are multiple ways to install this tools (CocoaPods, Homebrew, Mint) and it contains over 75 rules. There is in-depth configuration for each rule and the ability to define custom rules from the configuration file. There is also very good documentation both within the tool's help and online for each rule.

Pros:
- Multiple ways to install the tool (CocoaPods, Homebrew, Mint)
- Appears to work independent of the installed Swift version
- Both auto correct and lint options
- Use of configuration files to enable/disable rules
- Xcode Integration with Build Phase run script
- CLI for Git hook and CI build step
- Large number of rules
Cons:
- Doesn't appear have CLI argument for configuration file (file must be placed in directory where tool is run)

Unit test
Functional test (Fake network layer)
Performance test
Test harness? The current plan is Core will not share any testable.
Compatibility test (Hermetic test)? No

Epic: Design docs

Design docs
Contracts of Core