Merge branch 'release/3.3.5'

Cartfile

@@ -1,4 +1,4 @@
-github "SRGSSR/SRGMediaPlayer-iOS" "2.4"
-github "SRGSSR/srgdataprovider-ios" "6.0.1"
+github "SRGSSR/SRGMediaPlayer-iOS" "2.4.1"
+github "SRGSSR/srgdataprovider-ios" "6.0.2"
 github "SRGSSR/tagcommander-ios" "4.1.5_4.1.3"
 github "comScore/ComScore-iOS-SDK" "92f34897cd7659d56bb5a3e9e85b808cf3758bda"

Cartfile.resolved

@@ -1,8 +1,8 @@
 github "Mantle/Mantle" "2.1.0"
 github "SRGSSR/MAKVONotificationCenter" "d5af67218b3b7b49660a43edef5e6eb9c437d670"
-github "SRGSSR/SRGMediaPlayer-iOS" "2.4"
+github "SRGSSR/SRGMediaPlayer-iOS" "2.4.1"
 github "SRGSSR/libextobjc" "46f179fbba8dde2a3eb3da284919789b78aac441"
-github "SRGSSR/srgdataprovider-ios" "6.0.1"
+github "SRGSSR/srgdataprovider-ios" "6.0.2"
 github "SRGSSR/srglogger-ios" "1.0.2"
 github "SRGSSR/tagcommander-ios" "4.1.5_4.1.3"
 github "comScore/ComScore-iOS-SDK" "92f34897cd7659d56bb5a3e9e85b808cf3758bda"

Framework/Sources/Core/SRGAnalyticsConfiguration.h

@@ -11,7 +11,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  *  @name Supported business units
  */
-typedef NSString * SRGAnalyticsBusinessUnitIdentifier NS_STRING_ENUM;
+typedef NSString * SRGAnalyticsBusinessUnitIdentifier NS_TYPED_ENUM;
 
 OBJC_EXPORT SRGAnalyticsBusinessUnitIdentifier const SRGAnalyticsBusinessUnitIdentifierRSI;
 OBJC_EXPORT SRGAnalyticsBusinessUnitIdentifier const SRGAnalyticsBusinessUnitIdentifierRTR;

Framework/Sources/Core/UIViewController+SRGAnalytics.h

@@ -15,13 +15,14 @@ NS_ASSUME_NONNULL_BEGIN
  *  describes the data to send with such events. The only method required by this protocol is `srg_pageViewTitle`, 
  *  which provides the name to be used for the view events.
  *
- *  By default, if a view controller conforms to the `SRGAnalyticsViewTracking` protocol, a view event will
- *  automatically be sent when it is presented (when `-viewWillAppear:` is called), or when the application 
- *  returns from background while the view controller is visible.
+ *  By default, if a view controller conforms to the `SRGAnalyticsViewTracking` protocol, a page view event will
+ *  automatically be sent when it is presented for the first time (i.e. when `-viewDidAppear:` is called for
+ *  the first time). In addition, a page view event will be automatically sent every time the application returns
+ *  from background while the view controller is visible.
  *
  *  If you want to control when page view events are sent, however, you can implement the optional `srg_isTrackedAutomatically`
- *  method to return `NO`, disabling the mechanism described above. In this case you are responsible of calling the
- *  `-[UIViewController trackPageView]` method appropriately when you want the measurement event to be recorded. This 
+ *  method to return `NO`, disabling the mechanisms described above. In this case you are responsible of calling the
+ *  `-[UIViewController trackPageView]` method appropriately when you want the measurement events to be recorded. This
  *  approach is useful when the labels are not available at the time `-viewDidAppear:` is called, e.g. if they are 
  *  retrieved from a web service request started when the view controller gets displayed.
  *
@@ -45,6 +46,12 @@ NS_ASSUME_NONNULL_BEGIN
  *  the `-[UIViewController trackPageView]` method manually when a view event must be recorded.
  *
  *  @return `YES` iff automatic tracking must be enabled, `NO` otherwise.
+ *
+ *  @discussion Automatic apparition tracking is considered only the first time a view controller is displayed. If
+ *              the value returned by `srg_trackedAutomatically` is changed after a view controller was already displayed,
+ *              no page view will be automatically sent afterwards. For this reason, it is recommended that the value
+ *              returned by `srg_trackedAutomatically` should never be dynamic: Either return `YES` or `NO` depending
+ *              on which kind of tracking you need.
  */
 @property (nonatomic, readonly, getter=srg_isTrackedAutomatically) BOOL srg_trackedAutomatically;
 

Framework/Sources/Core/UIViewController+SRGAnalytics.m

@@ -13,6 +13,7 @@
 
 // Associated object keys
 static void *s_observerKey = &s_observerKey;
+static void *s_appearedOnce = &s_appearedOnce;
 
 // Swizzled method original implementations
 static void (*s_viewDidAppear)(id, SEL, BOOL);
@@ -41,15 +42,15 @@ + (void)load
 
 - (void)srg_trackPageView
 {
-    return [self srg_trackPageViewForced:YES];
+    return [self srg_trackPageViewAutomatic:NO];
 }
 
-- (void)srg_trackPageViewForced:(BOOL)forced
+- (void)srg_trackPageViewAutomatic:(BOOL)automatic
 {
     if ([self conformsToProtocol:@protocol(SRGAnalyticsViewTracking)]) {
         id<SRGAnalyticsViewTracking> trackedSelf = (id<SRGAnalyticsViewTracking>)self;
 
-        if (! forced && [trackedSelf respondsToSelector:@selector(srg_isTrackedAutomatically)] && ! [trackedSelf srg_isTrackedAutomatically]) {
+        if (automatic && [trackedSelf respondsToSelector:@selector(srg_isTrackedAutomatically)] && ! [trackedSelf srg_isTrackedAutomatically]) {
             return;
         }
 
@@ -85,8 +86,14 @@ static void swizzled_viewDidAppear(UIViewController *self, SEL _cmd, BOOL animat
 {
     s_viewDidAppear(self, _cmd, animated);
 
-    if ([self isMovingToParentViewController]) {
-        [self srg_trackPageViewForced:NO];
+    // Track a view controller at most once automatically when appearing. This covers all possible appearance scenarios,
+    // e.g.
+    //    - Moving to a parent view controller
+    //    - Modal presentation
+    //    - View controller revealed after having been initially hidden behind a modal view controller
+    if (! [objc_getAssociatedObject(self, s_appearedOnce) boolValue]) {
+        [self srg_trackPageViewAutomatic:YES];
+        objc_setAssociatedObject(self, s_appearedOnce, @YES, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
     }
 
     // An anonymous observer (conveniently created with the notification center registration method taking a block as
@@ -96,7 +103,7 @@ static void swizzled_viewDidAppear(UIViewController *self, SEL _cmd, BOOL animat
     id observer = [[NSNotificationCenter defaultCenter] addObserverForName:UIApplicationWillEnterForegroundNotification object:nil queue:nil usingBlock:^(NSNotification * _Nonnull notification) {
         @strongify(self)
 
-        [self srg_trackPageViewForced:NO];
+        [self srg_trackPageViewAutomatic:YES];
     }];
     objc_setAssociatedObject(self, s_observerKey, observer, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
 }

SRGAnalytics.xcodeproj/project.pbxproj

@@ -1211,7 +1211,7 @@
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
 				IPHONEOS_DEPLOYMENT_TARGET = 9.0;
-				MARKETING_VERSION = 3.3.4;
+				MARKETING_VERSION = 3.3.5;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = iphoneos;
 			};
@@ -1260,7 +1260,7 @@
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
 				IPHONEOS_DEPLOYMENT_TARGET = 9.0;
-				MARKETING_VERSION = 3.3.4;
+				MARKETING_VERSION = 3.3.5;
 				SDKROOT = iphoneos;
 				VALIDATE_PRODUCT = YES;
 			};

docs/Getting-started.md

@@ -46,7 +46,7 @@ Be careful when using custom labels, though, and ensure your custom keys do not
 
 View controllers represent the units of screen interaction in an application, this is why page view measurements are primarily made on view controllers. All methods and protocols for view controller tracking have been gathered in the `UIViewController+SRGAnalytics.h` file.
 
-View controller measurement is an opt-in, in other words no view controller is tracked by default. For a view controller to be tracked, the recommended approach is to have it conform to the `SRGAnalyticsViewTracking` protocol. This protocol requires a single method to be implemented, returning the view controller title to be used for measurements. By default, once a view controller implements the `SRGAnalyticsViewTracking` protocol, it automatically generates a page view when it appears on screen, or when the application wakes up from background with the view controller displayed.
+View controller measurement is an opt-in, in other words no view controller is tracked by default. For a view controller to be tracked, the recommended approach is to have it conform to the `SRGAnalyticsViewTracking` protocol. This protocol requires a single method to be implemented, returning the view controller title to be used for measurements. By default, once a view controller implements the `SRGAnalyticsViewTracking` protocol, it automatically generates a page view when it first appears on screen, or when the application wakes up from background with the view controller displayed.
 
 The `SRGAnalyticsViewTracking` protocol supplies optional methods to specify other custom measurement information (labels). If the required information is not available when the view controller appears, you can disable automatic tracking by implementing the optional `-srg_isTrackedAutomatically` protocol method, returning `NO`. You are then responsible of calling `-trackPageView` on the view controller when the data required by the page view is available.
 
@@ -89,7 +89,7 @@ and implement the methods you need to supply measurement information:
 @end
 ```
 
-When the view is opened or if the view is visible on screen when waking up the application, this information will be automatically sent.
+When the view is opened for the first time, or if the view is visible on screen when waking up the application, this information will be automatically sent.
 
 Note that the labels might differ depending on the service they are sent to. Be sure to apply the conventions required for measurements of your application. Moreover, custom information requires the corresponding variables to be defined for TagCommander first (unlike comScore information which can be freely defined).