:green_apple: Apple Frameworks

!CircleCI
!Platforms

- OS: iOS 10+, tvOS 12+
- Languages: Swift 5.1, frameworks can be used in Swift and Objective-C
- Tool requirements: Xcode 11.3, Cocoapods 1.8.3
- License: Appache 2.0

Note: Please do not change this document directly. If you need to update documentation use template README.md.ejs file.

:paperclip: Table of contents

- Overview
- Frameworks List
- Usage
- Folder Structure
- FrameworksData.plist
- How to add new framework?
- How to update existing framework?
- How it works?

:eyeglasses: Overview

This respository is the main container for general frameworks and plugins for ZappApple project. Each frameworks defined here support cocoapods as a dependency manager.

:fax: Frameworks List

##### ZappCore: 0.6.4
- Description: Contain plugin protocols, helper methods that can be used by any Zapp plugin or framework
- Documentation

##### ZappApple: 0.1.4
- Description: Contain data stucture to start Zapp application.
- Documentation

$3

#### Type: Analytics

##### Google Analytics Web Based API: 0.6.0
- Description: This plugin allow to add Google Analytics as agent.
- Documentation
- Manifest:
- iOS
- tvOS

#### Type: Crashlogs

##### MS App Center: 4.3.0
- Description: App center crash logs service.
- Documentation
- Manifest:
- iOS

#### Type: Player Dependant

##### Google Interactive Media Ads: 0.5.4
- Description: This plugin allow to add Google Interactive Media Ads to supported players.
- Documentation
- Manifest:
- iOS
- tvOS

:pencil2: Usage

* To use any framework availible in this repo add cocoapods dependency in podfile.

Example:
``ruby
pod 'ZappCore', :git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag => '2020.15.0.20-1-6'
`

* To use any plugin availible in this repo please use UI Builder Environment. All Plugins use npm packages as a package delivery and added in the application as dev cocoapods dependencies

:file_folder: Folder Structure

`swift
Apple Framworks
├── docs // Contains generated documentation for the frameworks. Content is generated automatically.
├── fastlane // Configuration of the fastlane deployment tool used in CI.
├── Frameworks // Frameworks data seperated by folders.
│ ├── *FrameworkName // All Frameworks, not part of ZAPP PLUGINS type Contains in the Root.
│ │ ├── .jazzy.yaml // Jazzy configuration file that defined to create auto generated docs
│ │ ├── Files // Files that are relevant for the framework.
│ │ │ ├── iOS // Files that can be used in iOS only
│ │ │ ├── tvOS // Files that can be used in tvOS only
│ │ │ ├── Tests // Unit test files
│ │ │ └── Universal // Files that can be used in iOS and tvOS
│ │ └── Templates // Template files relevant for framework automation.
│ │ │ ├── .jazzy.yaml.ejs // Jazzy template configuration file that is defined to create auto generated docs.
│ │ │ └── FrameworkName.podpec.ejs // Cocoapods template dependency.
│ └── *FrameworkName // All Frameworks, is part of ZAPP PLUGINS type.
│ ├── *FrameworkName // All Frameworks, is part of ZAPP PLUGINS type.
│ │ ├── .jazzy.yaml // Jazzy configuration file that defined to create auto generated docs
│ │ ├── Files // Files that are relevant for the framework.
│ │ │ ├── iOS // Files that can be used in iOS only
│ │ │ ├── tvOS // Files that can be used in tvOS only
│ │ │ ├── Tests // Unit test files
│ │ │ ├── src // Npm package files, any java script code if plugin needed
│ │ │ ├── FrameworkName.podspec // Cocoapods dependency file
│ │ │ ├── package.json // Node package file.
│ │ │ └── Universal // Files that can be used in iOS and tvOS
│ │ ├── Manifest // ZAPP PLUGINS manifest describes plugin created by Zappifest.
│ │ │ ├── ios.json // Generated manifest for ios ZAPP PLUGIN structure. All changes must be done in ios.json.ej
│ │ │ ├── tvos.json // Generated manifest for tvos ZAPP PLUGIN structure. All changes must be done in tvos.json.ej
│ │ ├── Templates // Template files relevant for framework automation.
│ │ │ ├── ios.json.ejs // Template manifest for ios ZAPP PLUGIN structure.
│ │ │ ├── tvos.json.ejs // Template manifest for tvos ZAPP PLUGIN structure.
│ │ │ ├── .jazzy.yaml.ejs // Jazzy template configuration file that is defined to create auto generated docs.
│ └── └── └── FrameworkName.podpec.ejs // Cocoapods template dependency.
├── FrameworksApp // General client app that each framework is using to unit test and generate project.
├── Scripts // Automotization scripts. All scripts defined in JavaScript.
├── .versions_automation.json // Automation file, must not be changed by user. Contains JSON with title and version of each framework.
├── FrameworksData.plist // Contains information about frameworks: title, version and etc. Only in this file user must change a version of new framework during update
├── Gemfile // Ruby packages.
├── LICENSE // Repo licence type.
├── package.json // Java Script packages.
├── README.md // Git documentations file. All changes must be done in README.md.ejs
├── README.md.ejs // Git documentations template file.
└── *.podspec // Cocoapods dependency files for all non plugins frameworks.
`

:pencil2: FrameworksData.plist

`swift
Dictionary
├── Framework/Plugin Id // Key described identifier of the item.
│ ├── version_id // Current version of the item based on major/minor/bug 1.0.0 convention.
└── └── plugin // Define if item is a framework or plugin.
`

:page_facing_up: How to add new framework

Create Framework

- Create branch new_framework_name
- Use Folder Structure article to check expected your framework folder structure.

- Open FrameworksData.plist file in the root of your repo:
- Add new value dictionary value. As a key use your framework_id
- Inside your dictionary add key version_id value version number based on major/minor/bug 1.0.0 convention.

- Open Frameworks folder in Root of the repo and create with framework_id as folder name. In future mention of this folder will be called as framework root folder.
- Create Files folder in your framework's root folder. This folder will be used for the source code of your framework.
- Create folder iOS if you have files relevant only for iOS
- Create folder tvOS if you have files relevant only for tvOS
- Create folder Universal If you have universal file for iOS and tvOS
- Note: single framework can have all three types of folders if it supports ios and tvos.
- Create folder Tests for unit tests.

- Create Cocoapods podspec file for your framework in root of the repo folder.
- podspec name must be same name as the framework_id. Example: MyFramework.podspec
- Prepare podspec based of your frameworks needs.
- Add test_spec and define path to your Unit test files
- If framework supports tvos and ios dependency must be defined in same podspec file.
- Example
`ruby
Pod::Spec.new do |s|
s.name = 'ZappCore'
s.version = '0.6.1'
s.summary = 'General Applicaster iOS and tvOS framework that provides protocol'
s.ios.deployment_target = '10.0'
s.tvos.deployment_target = '10.0'
s.swift_versions = '5.1'
s.description = <<-DESC
'General Applicaster iOS and tvOS framework that provides protocol and this lowest hierarchy layer'
DESC

s.homepage = 'https://github.com/applicaster/AppleApplicasterFrameworks.git'
s.license = 'Appache 2.0'
s.author = { 'a.kononenko@applicaster.com' => 'a.kononenko@applicaster.com' }
s.source = { :git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag => "2020.1.13.16-1-4" }

s.source_files = 'Frameworks/ZappCore/Files/Universal/*/.{swift}'

s.test_spec 'UnitTests' do |sp|
sp.source_files = 'Frameworks/ZappCore/Files/Tests/**'
end
end
`

- Create Podfilecocoapods dependecy and configure it for the project in Framework's root folder.
- In the podfile define all dependancy that may needed for your framework.
- Define your framework as develement pod with testspecs
- Make sure that share_schemes_for_development_pods will be added, it export cocoapods schemes from xsworkspace.
- Note: this Podile will be used by automation to unit test your framework and generare jazzy docs
- Example:
`ruby
source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'
install! 'cocoapods', :share_schemes_for_development_pods => true
project '../../FrameworksApp/FrameworksApp.xcodeproj'

pre_install do |installer|
# workaround for https://github.com/CocoaPods/CocoaPods/issues/3289
Pod::Installer::Xcode::TargetValidator.send(:define_method, :verify_no_static_framework_transitive_dependencies) {}
end

target 'FrameworksApp' do
supports_swift_versions '5.1'
use_frameworks!
pod 'ZappCore', :path => '../../ZappCore.podspec'
pod 'ZappApple', :path => '../../ZappApple.podspec', :testspecs => ['UnitTests']

target 'FrameworksAppTests' do
inherit! :search_paths
end

end

post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['CODE_SIGNING_REQUIRED'] = "NO"
config.build_settings['CODE_SIGNING_ALLOWED'] = "NO"
end
end
end
`
- Create file .jazzy.yaml with configuration of Jazzy documentation. Details configure Jazzy can be founded in Jazzy Repo or copied from existing frameworks.
- Make sure that you define in xcode arguments your framework scheme.
- Example:
`swift
module: ZappFirebaseAnalytics
module_version: "0.2.0"

author: "Applicaster ltd."
copyright: "© 2019 Applicaster ltd. under Appache 2.0."

xcodebuild_arguments: ["-scheme", "ZappCore"]
author_url: https://www.applicaster.com
github_url: https://github.com/applicaster/AppleApplicasterFrameworks/tree/master/Frameworks/Plugins/Analytics/Firebase/ZappFirebaseAnalytics

output: "../../../../../docs/ZappFirebaseAnalytics"
clean: true
min_acl: "private"
sdk: [iphone, appletv]
theme: jony
`
- Create Templates folder in your framework's root folder. In this folder you will be provided data for automated deployment. Templates files use structure of ejs.
- Copy the .jazzy.yaml file created before in path and rename it to .jazzy.yaml.ejs. Change field to module_version: "<%= version_id %>".
- Copy FrameworkName.podspec file created before from root repo folder and rename it to FrameworkName.podspec.ejs.
- Change field to s.version = '<%= version_id %>'.
- Change field to s.source = { :git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag => '<%= new_tag %>' }

- Go to Framework's root folder and call pod install.
- Cocoapods will generate FrameworkName
- Open it make sure FrameworkName scheme is share and build and start unit tests.
- Open README.md.ejs in the root of the repo.
- Add new framework under # Frameworks List title with format #### Framework readable name: <%= framework_id %>. In automation where framework_id will be populated value version_id from the FrameworksData.plist
- Add description.
- Add link to generated documentation.
- Example:
`swift
# Frameworks List

#### ZappCore: <%= ZappCore %>
- Description: Contain plugin protocols, helper methods that can be used by any Zapp plugin or framework
- Documentation
`
- Final check of you framework.
- Go to root Framework's folder and call in terminal node Scripts/validateExistingFrameworks.js It will check if you have all folders and FrameworksData.plist defined properly.
- Make sure that generated xcworkspace of your Framework build and start unit test of your framework's scheme.
- Templates are ready.
- Readme documentation added in the README.md.ejs file
- Push code and create PR. Fill PR template.
- After review merge code.

Create Zapp Plugin

- Create branch new_framework_name

- Use Folder Structure article to check expected your framework folder structure.

- Open FrameworksData.plist file in the root of your repo:
- Add new value dictionary value. As a key use your framework_id
- Inside your dictionary add key version_id value version number based on major/minor/bug 1.0.0 convention.
- Add key plugin with value true.
- Open Frameworks/Plugins folder in Root of the repo and create with plugin_id as folder name. In future mention of this folder will be called as plugin root folder

- Create Files folder in your framework's root folder
- Create folder iOS if you have files relevant only for iOS
- Create folder tvOS if you have files relevant only for tvOS
- Create folder Universal If you have universal file for iOS and tvOS
- Note: single framework can have all three types of folders if it supports ios and tvos.
- Create src folder if you need java script files.
- Create folder Tests for unit tests.
- Add file package.json to defined your plugin as npm dependancy.
- Example:
`JSON
{
"name": "@applicaster/quick-brick-google-ima-client",
"version": "0.5.3",
"description": "",
"main": "src/index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"files": [
"tvos",
"ios",
"Universal",
"src",
"ZappGoogleInteractiveMediaAds.podspec"
],
"repository": {
"type": "git",
"url": "git+https://github.com/applicaster/AppleApplicasterFrameworks"
},
"keywords": [],
"author": "",
"license": "ISC",
"bugs": {
"url": "https://github.com/applicaster/AppleApplicasterFrameworks"
},
"homepage": "https://github.com/applicaster/AppleApplicasterFrameworks"
}
`
- Add file podspec to define cocoapods denendancy
- podspec name must be same name as the plugin_id. Example: MyFramework.podspec
- Prepare podspec based of your plugins needs.
- Add test_spec and define path to your Unit test files
- If framework supports tvos and ios dependency must be defined in same podspec file.
- Example
`ruby
Pod::Spec.new do |s|
s.name = "ZappGoogleInteractiveMediaAds"
s.version = '0.5.3'
s.swift_versions = '5.1'

s.summary = "ZappGoogleInteractiveMediaAds"
s.description = "This plugin allow to add Google Interactive Media Ads to supported players."
s.homepage = 'https://github.com/applicaster/AppleApplicasterFrameworks.git'
s.license = 'Appache 2.0'
s.author = "Applicaster LTD."
s.source = {
:git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git',
:tag => "2020.1.13.22-1-8"
}

s.ios.deployment_target = '10.0'
s.tvos.deployment_target = '10.0'
s.tvos.vendored_frameworks = 'tvOS/GoogleInteractiveMediaAds.framework'
s.tvos.preserve_paths = 'tvOS/GoogleInteractiveMediaAds.framework'

s.ios.source_files = 'Universal/*/.swift'
s.tvos.source_files = ['Universal/*/.swift',
'tvOS/*/.swift'
]
s.ios.dependency 'GoogleAds-IMA-iOS-SDK', '= 3.11.1'

s.dependency 'ZappCore'

s.xcconfig = { 'ENABLE_BITCODE' => 'YES',
'OTHER_LDFLAGS' => '$(inherited) -framework "GoogleInteractiveMediaAds"',
'LIBRARY_SEARCH_PATHS' => '$(inherited) "${PODS_ROOT}"/**',
'CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES' => 'YES',
'ENABLE_TESTABILITY' => 'YES',
'OTHER_CFLAGS' => '-fembed-bitcode',
'FRAMEWORK_SEARCH_PATHS' => '/Applications/Xcode.app/Contents/Developer/Library/Frameworks'
}

s.test_spec 'UnitTests' do |sp|
sp.source_files = 'Tests/**'
end
end
`

- Create Podfilecocoapods dependecy and configure it for the project in Framework's root folder.
- In the podfile define all dependancy that may needed for your framework.
- Define your framework as develement pod with testspecs
- Make sure that share_schemes_for_development_pods will be added, it export cocoapods schemes from xsworkspace.
- Note: this Podile will be used by automation to unit test your framework and generare jazzy docs
- Example:
`ruby
source 'https://cdn.cocoapods.org/'
platform :ios, '10.0'
install! 'cocoapods', :share_schemes_for_development_pods => true
project '../../../FrameworksApp/FrameworksApp.xcodeproj'

pre_install do |installer|
# workaround for https://github.com/CocoaPods/CocoaPods/issues/3289
Pod::Installer::Xcode::TargetValidator.send(:define_method, :verify_no_static_framework_transitive_dependencies) {}
end

target 'FrameworksApp' do
supports_swift_versions '5.1'
use_frameworks!
pod 'ZappGoogleInteractiveMediaAds', :path => 'Files/ZappGoogleInteractiveMediaAds.podspec', :testspecs => ['UnitTests']
pod 'ZappCore', :path => '../../../ZappCore.podspec'

target 'FrameworksAppTests' do
inherit! :search_paths
end

end

post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['CODE_SIGNING_REQUIRED'] = "NO"
config.build_settings['CODE_SIGNING_ALLOWED'] = "NO"
end
end
end
`
- Create file .jazzy.yaml with configuration of Jazzy documentation. Details configure Jazzy can be founded in Jazzy Repo or copied from existing frameworks.
- Make sure that you define in xcode arguments your framework scheme.
- Example:
`swift
module: ZappFirebaseAnalytics
module_version: "0.2.0"

author: "Applicaster ltd."
copyright: "© 2019 Applicaster ltd. under Appache 2.0."

xcodebuild_arguments: ["-scheme", "ZappCore"]
author_url: https://www.applicaster.com
github_url: https://github.com/applicaster/AppleApplicasterFrameworks/tree/master/Frameworks/Plugins/Analytics/Firebase/ZappFirebaseAnalytics

output: "../../../../../docs/ZappFirebaseAnalytics"
clean: true
min_acl: "private"
sdk: [iphone, appletv]
theme: jony
`
- Create Templates folder in your framework's root folder. In this folder you will be provided data for automated deployment. Templates files use structure of ejs.
- Copy the .jazzy.yaml file created before in path and rename it to .jazzy.yaml.ejs. Change field to module_version: "<%= version_id %>".
- Copy FrameworkName.podspec file created before from root repo folder and rename it to FrameworkName.podspec.ejs.
- Change field to s.version = '<%= version_id %>'.
- Change field to s.source = { :git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag => '<%= new_tag %>' }
- Create manifest file using Zappifest for ios if plugin support it. Rename it to ios.json.ejs
- Change field to "manifest_version": "<%= version_id %>"
- Change field to :git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag
- Create manifest file using Zappifest for tvos if plugin support it. Rename it to tvos.json.ejs
- Change field to "manifest_version": "<%= version_id %>"
- Change field to "FrameworkName": ":git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag => '<%= new_tag %>'"

- Go to Framework's root folder and call pod install.
- Cocoapods will generate PluginName
- Open it make sure PluginName scheme is share and build and start unit tests.
- Open README.md.ejs in the root of the repo.
- Add new framework under # Frameworks List title with format #### Framework readable name: <%= framework_id %>. In automation where framework_id will be populated value version_id from the FrameworksData.plist
- Find plugin type. Example ### Type: Analytics
- If type does not exist under section. ## Zapp Plugins add new type ### Type: New Type
- Add new plugin title with format #### Plugin readable name: <%= framework_id %>. Where framework_id must be a value defined in FrameworksData.plist
- Add description.
- Add link to generated documentation.
- Add links to Zapp manifests.
- Example:
``swift
### Type: Analytics

#### Google Analytics: <%= ZappGoogleAnalytics %>
- Description: Google Analytics provider, deliver passed analytics data to service Google Analytics
- Documentation
- Manifest:
- iOS
- tvOS
`
- Final check of you framework.
- Go to root Framework's folder and call in terminal node Scripts/validateExistingFrameworks.js It will check if you have all folders and FrameworksData.plist defined properly.
- Make sure that generated xcworkspace of your Framework build and start unit test of your framework's scheme.
- Manifest prepared
- Templates are ready.
- Readme documentation added in the README.md.ejs file
- Push code and create PR. Fill PR template.
- After review merge code.

:page_with_curl: How to update existing framework

- Create branch framework_name_update_version_id
- Update framework code. Based on rules described in creation new framework
- Update version of your framework in frameworksData.plist based on major/minor/bug 1.0.0 convension.
- Push code and create PR. Fill PR template.
- After review merge code.

:mortar_board: How it works?

- All of the automation scripts are contained inside of the Scripts folder
- Automation contains two main scripts.
- Validate Frameworks: It checks if defined frameworks in FrameworksData.plist has all files that needed to support framework. This script is called on each commit. If validation failed CI build will be finished with fail
- Publish Frameworks: Script checks if framework needs to be published. Previous frameworks data saved in .versions_automation.json. It compares new data in FrameworksData.plist and .versions_automation.json all diffs in frameworks or not existing will be published. This script is called on master branch only. Script is will do the following:
- Get current date in format 2020.15.0.20-1-6 This string will be used as git tag
- Go throught all templates that are in ejs format for frameworks that need to be updated. It updates to a new version number in ejs key <%= version_id %> and git tag in ejs key <%= new_tag %>.

Template List

| File name | Description | Zapp plugins only |
|--------|--------|--------|
| .jazzy.yaml.ejs |Documentation generator templte|NO|
| framework_name.podspec.ejs |Cocoapods podspec template|NO|
| ios.json.ejs |iOS Zapp plugin manifest template|YES|
| tvos.json.ejs |tvOS Zapp plugin manifest template|YES|

- Generate documentation for framework and saves it to docs folder.
- Srart Unit tests.
- Upload manifest to Zapp with Zappifest (Zapp plugins only).
- Upload npm dependencies (Zapp plugins only)
- Update Frameworks list template Readme.md.ejs to update latest availible framework version for documentation.
- Update file .versions_automation.json with latest changes if format {framework_name:version_id}`
- Commit, push and create tag git repo