README

ZergSupport is a toolkit for iPhone OS applications that communicate with Web
services. As a toolkit, the ZergSupport library provides a collection of classes
designed to simplify certain tasks. The library does not impose an application
design philosophy like a framework would, and it does not extend Apple-supplied
classes, so it can coexist with other framework code. ZergSupport is liberally
licensed under the OSI-approved non-viral MIT license.

The ZergSupport code is restricted to methods in the official SDK, so that it
can be used in App Store applications. The initial version of ZergSupport is
used by in StockPlay, which passed Apple's approval process, and is currently
ready for sale in the App Store.

The code in ZergSupport is completely covered by tests, which also serve as
usage examples. The rest of this README provides a conceptual map of the code.


INSTALLATION

An easy method for incorporating ZergSupport is using the zerg_xcode tool, which
was written with this express purpose. The generic method for incorporating
library code using zerg_xcode is described in detail at:

http://blog.costan.us/2009/02/iphone-development-and-code-sharing.html

The master branch will always have code that is guaranteed to pass Apple's
approval process. Code that can cause concerns (e.g. security mechanisms or code
containing low-level system calls) will be placed in experimental branches until
one application containing that code is approved for submission to the Apple
Store. The philosophy behind this decision is that ZergSupport is intended to
remove development headaches, not contribute to them.

ZergSupport is currently compatible with iPhone SDK 2.0 and above. 


TARGETS

ZergSupport provides 3 targets:
* ZergSupport includes "production" code that should be shipped with iPhone
  applications using the library. This library should be included in the iPhone
  application target.
* ZergTestSupport includes ZergSupport, and adds code that can be helpful in
  writing your own tests. This library should be included in test targets. The
  test targets do not need to include ZergSupport directly.
* ZergSupportTests contains the test code for the ZergSupport toolkit. The test
  cases have been separated from ZergTestSupport so you don't have to run them
  every time you change your own code.


SERVICES

ModelSupport tries to fill the gap Apple created by leaving out Core Data. Model
classes inherit from ZNModel, and specify their attributes by declaring
properties. ModelSupport models are designed with Web interaction in mind, and
therefore can handle attributes that are not specified are development time.
These attributes are preserved during serialization and deserialization, so
they can be used in future versions of the application, and when exchanging
models with Web services or other applications. For testing purposes, models can
be initialized from JSON literals, yielding more compact (but slower) source
code.

WebSupport is a one-method API for asynchronous data exchange with Web services.
It can encode parameters into the format that makes HTTP servers happy, and
it decodes responses in multiple formats (currently JSON, XML, CSV, and raw
data). The API seamlessly encodes and decodes ModelSupport models, and
transparently supports local:// URLs, which wouldn't work with NSURLConnection.

ControllerSupport has reusable logic for controllers communicating with Web
servers. Currently, it provides reusable data synchronization logic, and a
NSView-independent implementation of the Target-Action model.

FormatSupport is the string crunching backend of WebSupport. It's responsible
for encoding to x-www-url-encoded, decoding from JSON, XML and CSV, and
converting between different casing conventions. FormatSupport also implements
ObjectQuery, which can be used to pull objects from deeply nested Cocoa
collections, such as the results of JSON deserialization.

ImobileSupport addresses several disparate technologies specific to the iPhone
OS, and makes their use easier. Currently, ImobileSupport simplifies In-App
Purchases and Push Notifications. ImobileSupport also implements collecting
metrics on the application's runtime environment, such as the application's
bundle ID and version, device hardware model (e.g. iPod2,1), unique number
(UDID), and OS version.

CryptoSupport bundles code that is likely necessary for iPhone application
security, such as cryptographic primitives (encryption and signatures). At this
point, the code in CryptoSupport is not well integrated with the rest of the
toolkit.

TestSupport offers a healthy foundation for testing, by packing the necessary
subset of the Google Toolbox for Mac, as well as OCMock. On top of that, it
supports Rails-like fixtures for ModelSupport models. TestSupport is only
included in the testing targets, so you don't have to worry about the APL
license that comes with Google's code.


DOCUMENTATION

The best documentation for the code are the test cases. The top-level header
files (*Support.h) have overviews for the parts of the toolkit that they cover.
Specifications are more spotty among internal classes, and classes whose
interfaces don't feel ready.

The following blog posts highlight the most convincing features, and provide
code samples.

The main use case for the toolkit, with code samples:
http://blog.costan.us/2009/04/toolkit-for-iphone-web-service.html

Using JSON for a better life:
http://blog.costan.us/2009/05/iphone-web-service-toolkit-upgrade-json.html


CONTRIBUTING

If you find ZergSupport useful, and want to give back, the easiest way is to
improve the existing documentation. The next step up is implementing new
functionality, or fixing bugs. This can be demanding, because I care a lot about
maintaining full test coverage. To compensate for that, I will be happy to help
out with directions and ideas, or brainstorm on means of testing new code. You 
must be prepared to assign the copyright of your contributions to Zergling.Net,
and have your code released under the MIT license, to keep licensing legals
simple for ZergSupport's users. 

If your employment conditions or philosophy prevent you from contributing to
ZergSupport by development, you can buy StockPlay from the App Store, and thus
contribute indirectly.


TESTING

ZergSupport is designed to help communicating with outside services. Its tests
use mock services. This is the mock setup needed by the tests:

1. A testbed (zn_testbed) service running on Heroku infrastructure. The code is
at http://github.com/costan/zn_testbed/ and the testbed is hosted at
http://zn-testbed.heroku.com

2. Apple Push Notification Service certificates. Setup guide:
  * In the iPhone Developer Program Portal, go to App IDs, select New App ID.
    * (recommended) Use ZergSupport Tests for the description.
    * (recommended) Select an existing Bundle Seed ID, if one is available.
      This way, you can use your existing wildcard provisioning certificates to
      run ZergSupport tests.
    * Set the Bundle Identifier (App ID Suffix) to us.costan.ZergSupport, or
      modify the bundle ID on the ZergSupportTests target to match your setting.
    * Submit the creation form, then click on Configure next to the new App ID.
    * Check on Enable Push notifications checkbox.
    * Click on the Configure button next to Development Push SSL Certificate.
    * Follow the on-screen instructions to get a certificate in your keychain.
      TIP: You can use the same certificate signing request for the developer
           and for the production certificate.
  * Open Keychain.
    * Select the login keychain from the keychains list (top-left).
    * Select "My Certificates" from the category list (bottom-left).
    * Select the push certificate (the name will include "Push Services").
    * From the application menu, select File > Export Items..., and leave the
      password blank. Save the certificate inside the ZergSupport project, as
      ZergSupport/ImobileSupport/ZNPushNotificationsTestCertDev.p12
  * Repeat the steps above for the production certificate, save it as
    ZergSupport/ImobileSupport/ZNPushNotificationsTestCertProd.p12
  

3. An App Store application with the ID us.costan.ZergSupport. The application
must be for pay (for In-App Purchases). Setup guide:
  * In the iPhone Developer Program Portal, go to App IDs, click on the
    Configure button next to the App ID created at for Push Notifications.
    * Check the Enable In App Purchase checkbox.
  * Sign into iTunes connect.
    * Create a new application, set the pricing to Tier 1 or above (not Free).
      Everything else in the application description is not important.
    * Build the ZergSupport tests in Distribution mode, submit the binary to
      iTunes Connect. Any binary will work. Without a submitted binary, In-App
      Purchase tests will fail.
    * Go to Manage Your In-App Purchases, and setup the purchases described
      below. The purchases must be under the ZergSupport test application.

4. The following In-App Purchases:
  * A test subscription:
    * Reference Name: ZergSupport: Subscription Test
    * Product ID: net.zergling.ZergSupport.sub
    * Type: Subscription
    * Price Tier: 2
    * Cleared for Sale: Yes
    * Display Detail: Language - English
      * Name: 1 Month Subscription
      * Description: 1 Month Subscription Description 
  * A test premium feature:
    * Reference Name: ZergSupport: Feature Test
    * Product ID: net.zergling.ZergSupport.feature
    * Type: Non-Consumable
    * Price Tier: 4
    * Cleared for Sale: Yes
    * Display Detail: Language - English
      * Name: Awesome Feature
      * Description: Awesome Feature Description
  * A test cheap item:
    * Reference Name: ZergSupport: Cheap Subscription Test
    * Product ID: net.zergling.ZergSupport.sub_cheap
    * Type: Subscription
    * Price Tier: 1
    * Cleared for Sale: Yes
    * Display Detail: Language - English
      * Name: 1 Day Subscription
      * Description: Lowest possible price
  * A cancellation test item:
    * Reference Name: ZergSupport: Cancellation Test
    * Product ID: net.zergling.ZergSupport.cancel_me
    * Type: Consumable
    * Price Tier: 1
    * Cleared for Sale: Yes
    * Display Detail: Language - English
      * Name: Cancel This Purchase
      * Description: This item tests cancelled purchases. DON'T agree to buy it.