appleframeworks v0.0.1
:green_apple: Apple Frameworks
- 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
Zapp Plugins
Type: Analytics
Google Analytics Web Based API: 0.6.0
- Description: This plugin allow to add Google Analytics as agent.
- Documentation
- Manifest:
Type: Crashlogs
MS App Center: 4.3.0
- Description: App center crash logs service.
- Documentation
- Manifest:
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:
:pencil2: Usage
To use any framework availible in this repo add cocoapods dependency in podfile.
Example:
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
Repository has predefined structure if you want to add something, please conform to the strict structure rules defined below
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
This file provides information for automation system latest version of availible frameworks or plugins. To update the version of your framework or plugin must be changed in this file. Below will be described plist structure
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((#pencil2-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 keyversion_id
valueversion number
based onmajor/minor/bug
1.0.0
convention.Open
Frameworks
folder in Root of the repo and create withframework_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 folderiOS
if you have files relevant only for iOS - Create foldertvOS
if you have files relevant only for tvOS - Create folderUniversal
If you have universal file for iOS and tvOS - Note: single framework can have all three types of folders if it supportsios
andtvos
. - Create folderTests
for unit tests.Create Cocoapods
podspec
file for your framework in root of the repo folder. -podspec
name must be same name as theframework_id
. Example:MyFramework.podspec
- Preparepodspec
based of your frameworks needs. - Addtest_spec
and define path to yourUnit test files
- If framework supportstvos
andios
dependency must be defined in samepodspec
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
Podfile
cocoapods dependecy and configure it for the project in Framework's root folder. - In thepodfile
define all dependancy that may needed for your framework. - Define your framework as develement pod withtestspecs
- Make sure thatshare_schemes_for_development_pods
will be added, it exportcocoapods
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 inxcode arguments
your framework scheme.Example:
module: ZappFirebaseAnalytics module_version: "0.2.0" author: "Applicaster ltd." copyright: "© 2019 [Applicaster ltd.](http://bustoutsolutions.com) under [Appache 2.0](https://github.com/applicaster/AppleApplicasterFrameworks/blob/master/LICENSE)." 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 tomodule_version: "<%= version_id %>"
. - CopyFrameworkName.podspec
file created before from root repo folder and rename it toFrameworkName.podspec.ejs
. - Change field tos.version = '<%= version_id %>'
. - Change field tos.source = { :git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag => '<%= new_tag %>' }
Go to Framework's root folder and call
pod install
. - Cocoapods will generateFrameworkName
- Open it make sureFrameworkName
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 whereframework_id
will be populated valueversion_id
from theFrameworksData.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**](https://applicaster.github.io/AppleApplicasterFrameworks/ZappCore/index.html) ```
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 allfolders
andFrameworksData.plist
defined properly. - Make sure that generatedxcworkspace
of yourFramework
build and start unit test of your framework's scheme. - Templates are ready. - Readme documentation added in theREADME.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 keyversion_id
valueversion number
based onmajor/minor/bug
1.0.0
convention. - Add keyplugin
with valuetrue
.Open
Frameworks/Plugins
folder in Root of the repo and create withplugin_id
as folder name. In future mention of this folder will be called as plugin root folderCreate
Files
folder in your framework's root folder - Create folderiOS
if you have files relevant only for iOS - Create foldertvOS
if you have files relevant only for tvOS - Create folderUniversal
If you have universal file for iOS and tvOS - Note: single framework can have all three types of folders if it supportsios
andtvos
. - Createsrc
folder if you need java script files. - Create folderTests
for unit tests. - Add filepackage.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
Podfile
cocoapods dependecy and configure it for the project in Framework's root folder. - In thepodfile
define all dependancy that may needed for your framework. - Define your framework as develement pod withtestspecs
- Make sure thatshare_schemes_for_development_pods
will be added, it exportcocoapods
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 inxcode arguments
your framework scheme.Example:
module: ZappFirebaseAnalytics module_version: "0.2.0" author: "Applicaster ltd." copyright: "© 2019 [Applicaster ltd.](http://bustoutsolutions.com) under [Appache 2.0](https://github.com/applicaster/AppleApplicasterFrameworks/blob/master/LICENSE)." 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 tomodule_version: "<%= version_id %>"
. - CopyFrameworkName.podspec
file created before from root repo folder and rename it toFrameworkName.podspec.ejs
. - Change field tos.version = '<%= version_id %>'
. - Change field tos.source = { :git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag => '<%= new_tag %>' }
- Create manifest file using Zappifest for
ios
if plugin support it. Rename it toios.json.ejs
- Change field to
"manifest_version": "<%= version_id %>"
- Change field to `:git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag
- Change field to
- Create manifest file using Zappifest for
tvos
if plugin support it. Rename it totvos.json.ejs
- Change field to
"manifest_version": "<%= version_id %>"
- Change field to
"FrameworkName": ":git => 'https://github.com/applicaster/AppleApplicasterFrameworks.git', :tag => '<%= new_tag %>'"
- Change field to
- Create manifest file using Zappifest for
Go to Framework's root folder and call
pod install
. - Cocoapods will generatePluginName
- Open it make surePluginName
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 whereframework_id
will be populated valueversion_id
from theFrameworksData.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 %>
. Whereframework_id
must be a value defined inFrameworksData.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](https://analytics.google.com/) - [**Documentation**](https://applicaster.github.io/AppleApplicasterFrameworks/ZappGoogleAnalytics/index.html) - **Manifest:** - [iOS](https://zapp.applicaster.com/admin/plugin_versions?id=zapp_google_analytics&platform=ios) - [tvOS](https://zapp.applicaster.com/admin/plugin_versions?id=zapp_google_analytics&platform=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 allfolders
andFrameworksData.plist
defined properly. - Make sure that generatedxcworkspace
of yourFramework
build and start unit test of your framework's scheme. - Manifest prepared - Templates are ready. - Readme documentation added in theREADME.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 onmajor/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 inFrameworksData.plist
and.versions_automation.json
all diffs in frameworks or not existing will be published. This script is called onmaster
branch only. Script is will do the following: - Get current date in format2020.15.0.20-1-6
This string will be used asgit tag
- Go throught all templates that are in ejs format for frameworks that need to be updated. It updates to a newversion number
inejs
key<%= version_id %>
andgit tag
inejs
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](https://github.com/applicaster/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