updated readme, changelog, podspec and documentation. ready to merge …

…& tag

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Trustbadge
 
+## Version 0.8.0
+
+* The eMail is now optional for TRSOrder objects (and thus also for TRSCustomer objects). This allows processing orders for which the App does not collect an email address itself (for example in-app purchases). See updated README file. 
+
 ## Version 0.7.0
 
 * Changed the popup card that is shown when the user clicks on the seal image to the standard trustcard that is also used in web shops. What exactly is shown on that card also depends on what services the shop has booked at Trusted Shops.

Pod/Classes/Public/TRSOrder.h

@@ -96,6 +96,11 @@ typedef NS_ENUM(NSUInteger, TRSNextActionFlag) {
  a member at Trusted Shops.
  Since this requires user interaction, the calls to do so will open a lightbox in the UI and display the needed
  information for the user & process necessary interaction in a webview.
+ An exception to this behavior is when the provided information is incomplete. Then a more elaborate interaction is 
+ required, so the app switches to mobile Safari & displays a regular webpage for the user to enter missing and/or 
+ additional information. An example for this would be if you cannot provide an email address.
+ Another case would be if the given currency doesn't match the settings of your account at Trusted Shops (so you
+ should provide the correct currency that matches your shop/MyTS account).
  */
 @interface TRSOrder : NSObject
 
@@ -194,7 +199,7 @@ typedef NS_ENUM(NSUInteger, TRSNextActionFlag) {
  
  @param trustedShopsID Your Trusted Shops ID.
  @param apiToken The token to authenticate your app for the (remote) API at Trusted Shops. Currently can be any `NSString`.
- @param email The email your customer used to make the purchase.
+ @param email The email your customer used to make the purchase. Specify `nil` if you don't have it.
  @param orderNo A string uniquely representing the order that was made.
  @param amount The actual value of the purchase. Typically a float or double greater than 0 and with 2 digits after the decimal point.
  @param currency A string denoting the purchase the transaction was made in, e.g. `@"EUR"`.
@@ -223,7 +228,7 @@ typedef NS_ENUM(NSUInteger, TRSNextActionFlag) {
  
  @param trustedShopsID Your Trusted Shops ID.
  @param apiToken The token to authenticate your app for the (remote) API at Trusted Shops. Currently can be any `NSString`.
- @param email The email your customer used to make the purchase.
+ @param email The email your customer used to make the purchase. Specify `nil` if you don't have it.
  @param orderNo A string uniquely representing the order that was made.
  @param amount The actual value of the purchase. Typically a float or double greater than 0 and with 2 digits after the decimal point.
  @param currency A string denoting the purchase the transaction was made in, e.g. `@"EUR"`.
@@ -267,6 +272,8 @@ typedef NS_ENUM(NSUInteger, TRSNextActionFlag) {
  to be shown to the user, informing them about their status at Trusted Shops, the guarantee, etc.
  After the user has finished interacting with that dialog the onCompletion block will be called with
  `nil` as its `error` parameter.
+ If the provided information is incomplete (e.g. no email is specified), the app switches to mobile Safari
+ instead and displays a more elaborate page there for the user to provide missing information.
  @param onCompletion A block that is called after the object has been sent to the Trusted Shops API. 
  Its `error` parameter will be nil unless an error occured.
  @see validateWithCompletionBlock:

README.md

@@ -32,7 +32,7 @@ Trustbadge is available through [CocoaPods](http://cocoapods.org). To install
 it, simply add the following line to your Podfile:
 
 ```ruby
-pod "Trustbadge", "~> 0.7"
+pod "Trustbadge", "~> 0.8"
 ```
 
 #### Example project ####
@@ -198,7 +198,7 @@ To use this feature your app needs to add a few lines of code right after your c
 // create a TRSOrder object
 TRSOrder *anOrder = [TRSOrder TRSOrderWithTrustedShopsID:@"your TS-ID"                     // your TS-ID
                                                 apiToken:@"any string for now"             // just use any non-nil, non-empty string
-                                                   email:@"customer@example.com"           // your customer's email
+                                                   email:@"customer@example.com"           // your customer's email, or nil if you don't have it
                                                  ordernr:@"0815XYZ"                        // a unique identifier for the order
                                                   amount:[NSNumber numberWithDouble:28.73] // the total price as NSNumber
                                                     curr:@"EUR"                            // the currency, see documentation for valid values
@@ -223,7 +223,10 @@ anOrder.debugMode = YES; // see below for information on this!
 ```
 
 For a more detailed description of the methods and objects handling this process, see the SDK documentation.
-Please be aware that in some use-cases the user may be referred to an external (mobile) website opening on Safari (for example if this is the first time they purchase a Trusted Shops guarantee). The modal WebView closes in these instances, so once they get back they can keep on using your app as usual. Like is the case with the `TRSTrustbadgeView`, you can specify a `customPresentingViewController` object to manage the presentation of the displayed dialogue boxes during the finish process.
+Please be aware that in some use-cases the user may be referred to an external (mobile) website opening on Safari. This is only done when further input is required by the user that can't be properly shown in the displayed popup. For example, if you can't provide the user's email address to the SDK (for instance because the purchased goods are in-app purchases), they are referred to a site to enter it themselves (Trusted Shops needs this information for a proper checkout process).
+The modal WebView closes in these cases, so once users get back they can keep on using your app as usual. 
+You should only leave out the email address if you really don't have it, as this results in the best user experience during checkout (users won't leave your app).
+Like is the case with the `TRSTrustbadgeView`, you can specify a `customPresentingViewController` object to manage the presentation of the displayed dialogue boxes during the finish process.
 
 If you are developing your application and want to test this SDK feature __please be aware that unless the order object's `debugMode` property is set to `YES`, the generated data is sent to the Trusted Shops production database!__
 
@@ -239,7 +242,7 @@ Please contact your customer success manager directly or via [members@trustedsho
 ## 7. About this SDK ##
 
 #### Documentation ####
-The latest documentation can be found at [cocoadocs](http://cocoadocs.org/docsets/Trustbadge/0.7.0/).
+The latest documentation can be found at [cocoadocs](http://cocoadocs.org/docsets/Trustbadge/0.8.0/).
 All headers are documented according to the [appledoc](http://appledoc.gentlebytes.com/appledoc/) syntax, so you can also use that to directly include the docsets into your XCode.
 
 #### Data Privacy ####

Trustbadge.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = "Trustbadge"
-  s.version          = "0.7.0"
+  s.version          = "0.8.0"
   s.summary          = "Trusted Shops SDK for iOS"
   s.description      = <<-DESC
                        Use the Trustbadge and Trusted Shops guarantee in your iOS app.