Managing Analytics in a TCA app

2023-12-14T00:00:00+00:00

One of the core requirements of any enterprise app is analytics. It's essential if the company wants to know how their app is used, how they can improve it, and ultimately how they can maximise its profitability.

Integrating analytics into an app can be fairly easy using one of the many services that provide a way to log analytics with nice dashboards. Adding events to button presses, download results, or screen views can be very easy to do, but it can also take over the app and become invasive.

You can very quickly get into a state where the analytics in the app start to crowd the actual features of the app. Consistency doesn't exist as there are no real rules as to where the analytics should be done. And testing analytics becomes difficult when they are reported from button presses or scroll events in the view.

With TCA we have a well defined place to put all the logic of our apps: in the Action</code> of the Reducer</code>s.

Can we exploit this to make analytics just as well defined without also flooding the feature code?

My initial thought for analytics with TCA was to create a dependency that we can use to push our analytics through. In the reducer it looked something like this:

var</span> body: ReducerOf</span><</span>Self</span>> {</span></span>
  Reduce</span> {</span> state, action </span>in</span></span>
    switch</span> action </span>{</span></span>
    case</span> .buttonTapped</span>:</span></span>
      state.message</span> =</span> "Button tapped!"</span></span>
      return</span> .</span>merge</span>(</span></span>
        .</span>run</span> {</span> _</span> in</span></span>
          await</span> analyticsClient.</span>send</span>(</span>"ButtonTapped"</span>)</span></span>
        }</span>,</span></span>
        downloadEffect</span></span>
      )</span></span>
    }</span></span>
  }</span></span>
}</span></span></code></pre>
This works, but it doesn't solve the problems. The feature code of the app quickly gets overrun with analytics. In the example above the buttonTapped</code> action is really there to start a downloadEffect</code>, but it has to be merged with the analytics, making it harder to see what the app is actually doing.</p>
It gets messy.</p>
By leveraging the composability of TCA reducers, and creating our own reducer, we can create a much more elegant way of sending analytics that is just as powerful, but confined to its own dedicated space away from the feature code.</p>
If you want to jump ahead and just get the code, I have created an SPM package that you can use: swift-composable-analytics</a>.</p>
The core idea of this method is to still use a dependency to send analytics through, but to create a way to access that dependency through a dedicated reducer that does nothing other than send analytics. It means that the analytics code still remains close to the feature code, but just far enough away to not flood the feature code.</p>
The end goal looks like this:</p>
var</span> body:</span> some</span> ReducerOf</span><</span>Self</span>> {</span></span>
  // 1.</span></span>
  AnalyticsReducer</span> {</span> state, action </span>in</span></span>
    // 2.</span></span>
    switch</span> action </span>{</span></span>
    case</span> .buttonTapped</span>:</span></span>
      // 3.</span></span>
      return</span> .</span>event</span>(</span>name</span>:</span> "ButtonTapped"</span>)</span></span>
    }</span></span>
  }</span></span>
</span>
  Reduce</span> {</span> state, action </span>in</span></span>
    switch</span> action </span>{</span></span>
    case</span> .buttonTapped</span>:</span></span>
      state.message</span> =</span> "Button tapped!"</span></span>
      // 4.</span></span>
      return</span> downloadEffect</span></span>
    }</span></span>
  }</span></span>
}</span></span></code></pre>

We have a new AnalyticsReducer</code> that gives us state and action just like any other reducer. But this time state is immutable. This means that our analytics code cannot affect the state of the app.</li>
We have access to all the actions defined in the reducer, so we can send analytics for any event that can happen in the app. Whether it is the user tapping a button, the results of a successful download, or an error received from a service we interact with.</li>
The AnalyticsReducer</code> function just returns AnalyticsData</code>, so it can't run any custom effects. It is completely isolated from the feature code.</li>
The feature code of the app is unaffected. We just treat the feature code as the standard feature code. In this case, the button just returns the downloadEffect</code> without needing to worry about analytics at all.</li>
</ol>
That's the plan, and all of this is done with a surprisingly small custom reducer:</p>
import</span> Foundation</span></span>
import</span> ComposableArchitecture</span></span>
</span>
public struct</span> AnalyticsReducer</span><</span>State</span>,</span> Action</span>>:</span> Reducer</span> {</span></span>
  @</span>usableFromInline</span></span>
  let</span> toAnalyticsData:</span> (</span>State, Action</span>)</span> -></span> AnalyticsData</span>?</span></span>
</span>
  @</span>usableFromInline</span></span>
  @</span>Dependency</span>(</span>\.analyticsClient</span>)</span> var</span> analyticsClient</span></span>
</span>
  @</span>inlinable</span></span>
  public init</span>(</span>_</span> toAnalyticsData</span>: </span>@</span>escaping</span> (</span>State, Action</span>)</span> -></span> AnalyticsData</span>?</span>) {</span></span>
    self.</span>init</span>(</span>toAnalyticsData</span>:</span> toAnalyticsData, </span>internal</span>: ())</span></span>
  }</span></span>
</span>
  @</span>usableFromInline</span></span>
  init</span>(</span>toAnalyticsData</span>: </span>@</span>escaping</span> (</span>State, Action</span>)</span> -></span> AnalyticsData</span>?</span>, </span>internal</span>: </span>Void</span>) {</span></span>
    self.toAnalyticsData</span> =</span> toAnalyticsData</span></span>
  }</span></span>
</span>
  @</span>inlinable</span></span>
  public func</span> reduce</span>(</span>into</span> state</span>: </span>inout</span> State, </span>action</span>: Action</span>)</span> -></span> Effect</span><</span>Action</span>> {</span></span>
    guard let</span> analyticsData </span>=</span> toAnalyticsData</span>(</span>state, action</span>)</span> else</span> {</span></span>
      return</span> .none</span></span>
    }</span></span>
</span>
    return</span> .</span>run</span> {</span> _</span> in</span></span>
      analyticsClient.</span>sendAnalytics</span>(</span>analyticsData</span>)</span></span>
    }</span></span>
  }</span></span>
}</span></span></code></pre>
This AnalyticsReducer</code> requires a function from (state, action) -> AnalyticsData?</code>, and everything else is done for you. If you return nil</code> from the function then nothing happens. Only when you return the AnalyticsData</code> does this access the analyticsClient</code> and send the data to our analytics services.</p>
Now we just need to create an AnalyticsClient</code> to use to send events for us. By default in my package I have created a .consoleLogger</code> analytics client that logs events out to the console. It looks like this:</p>
extension</span> AnalyticsClient</span> {</span></span>
  public static var</span> consoleLogger: Self</span> =</span> .</span>init</span>(</span></span>
    sendAnalytics</span>: {</span> analytics </span>in</span></span>
      print</span>(</span>"[Analytics] ✅ </span>\(</span>analytics</span>)</span>"</span>)</span></span>
    }</span></span>
  )</span></span>
}</span></span></code></pre>
It has a single function, sendAnalytics</code>, that takes the data and logs it to the console.</p>
To create our own AnalyticsClient</code> that sends events to our own service we just need to implement this sendAnalytics</code> function. Here is an example of a client that is written to send analytics to Firebase and Crashlytics:</p>
import</span> Firebase</span></span>
import</span> FirebaseCrashlytics</span></span>
</span>
public extension</span> AnalyticsClient</span> {</span></span>
  static var</span> firebaseClient: Self</span> {</span></span>
    return</span> .</span>init</span>(</span></span>
      sendAnalytics</span>: {</span> analyticsData </span>in</span></span>
        switch</span> analyticsData </span>{</span></span>
        case let</span> .</span>event</span>(</span>name</span>:</span> name, </span>properties</span>:</span> properties</span>)</span>:</span></span>
          Firebase.Analytics.</span>logEvent</span>(</span>name, </span>parameters</span>:</span> properties</span>)</span></span>
</span>
        case</span> .</span>userId</span>(</span>let</span> id</span>)</span>:</span></span>
          Firebase.Analytics.</span>setUserID</span>(</span>id</span>)</span></span>
          Crashlytics.</span>crashlytics</span>()</span>.</span>setUserID</span>(</span>id</span>)</span></span>
</span>
        case let</span> .</span>userProperty</span>(</span>name</span>:</span> name, </span>value</span>:</span> value</span>)</span>:</span></span>
          Firebase.Analytics.</span>setUserProperty</span>(</span>value, </span>forName</span>:</span> name</span>)</span></span>
</span>
        case</span> .</span>screen</span>(</span>name</span>:</span> let</span> name</span>)</span>:</span></span>
          Firebase.Analytics.</span>logEvent</span>(</span>AnalyticsEventScreenView, </span>parameters</span>:</span> [</span></span>
            AnalyticsParameterScreenName</span>:</span> name</span></span>
          ]</span>)</span></span>
</span>
        case</span> .error</span>(</span>let</span> error</span>)</span>:</span></span>
          Crashlytics.</span>crashlytics</span>()</span>.</span>record</span>(</span>error</span>:</span> error</span>)</span></span>
        }</span></span>
      }</span></span>
    )</span></span>
  }</span></span>
}</span></span></code></pre>
We extend AnalyticsClient</code> to provide a .firebaseClient</code>, and in the sendAnalytics</code> function we just inspect the data that comes in and send it to the relevant Firebase or Crashlytics service.</p>
To start using this we just need to inject the dependency when we create the root Store</code> of the app:</p>
let</span> rootStore </span>=</span> Store</span>(</span>RootReducer.</span>State</span>()) {</span></span>
  RootReducer</span>()</span></span>
}</span> withDependencies</span>: {</span></span>
  $0.analyticsClient</span> =</span> .</span>merge</span>(</span>.consoleLogger, .firebaseClient</span>)</span></span>
}</span></span></code></pre>
This is all we need now to start sending analytics from anywhere in the app, and we can use merge</code> to add multiple analytics services to our app.</p>
Finally we come to testing. Because all of the analytics of our app are sent via actions in a reducer it means that our tests have access to all of them.</p>
And we can provide a function to expect analytics data that is really powerful for testing. In our test we can tell the TestStore</code> that we expect to receive certain analytics data, and if we don't receive that the test will fail.</p>
func</span> testButtonTapped</span>()</span> async throws</span> {</span></span>
  let</span> store </span>=</span> TestStore</span>(</span>RootReducer.</span>State</span>()) {</span></span>
    RootReducer</span>()</span></span>
  }</span> withDependencies</span>: {</span></span>
    $0.analyticsClient.</span>expect</span>(</span>.</span>event</span>(</span>"ButtonTapped"</span>))</span></span>
  }</span></span>
</span>
  store.</span>send</span>(</span>.buttonTapped</span>)</span></span>
}</span></span></code></pre>
This test is exhaustive too.</p>
If you don't expect an event and then an event is sent, it will fail. If you expect an event and it doesn't get sent, it will fail. If the expected event is different from the sent event, it will fail.</p>
So the test really does cover every eventuality.</p>
I have found this to be a really effective way to manage and send analytics throughout the apps I've worked on. Adding a new analytics service is just a case of creating a new client and injecting it at the root. All of the analytics throughout the app then start getting sent to the new service.</p>
I hope this has given you a brief insight into how to leverage reducers and actions. This is only one use case I have created, but there are a lot more ways of extending TCA to provide benefits like this.</p>
You can get my SPM package swift-composable-analytics</a> on GitHub.</p>

Oliver Foggin - analytics

Managing Analytics in a TCA app