appleframeworks

0.0.1 • Public • Published

🍏 Apple Frameworks

CircleCI Platforms GitHub license

  • 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.

📎 Table of contents

👓 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.

📠 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

Type: Crashlogs

MS App Center: 4.3.0

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:

✏️ 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

📁 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.

✏️ 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.

📄 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 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
    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:
    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:
      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 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:
          # 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 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:
       {
            "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:
    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:
      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 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:
          ### 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 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.

📃 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.

🎓 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**

      le 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

Readme

Keywords

Package Sidebar

Install

npm i appleframeworks

Weekly Downloads

3

Version

0.0.1

License

Apache-2.0

Unpacked Size

13.4 MB

Total Files

869

Last publish

Collaborators

  • applicaster-devs