Architecture

Last updated
Save as PDF

This is a high-level architecture for the iOS SDK, and is detailed in some cases at the class-level.

SDK Central

There is a central SDK class (RCHSDK) that is the entrypoint for all SDK interactions. It includes the following functionality:

Configure logging
Access default API client
Request builder factory methods

Constructing API Requests (Builders)

All API requests are constructed using an implementation of the builder pattern. There are several request builders that provide API endpoint abstractions. The builders are as follow:

RCHRequestBuilder: base class for all builders. Includes common functionality as well as the ability to add any arbitrary key/value pairs to a request.
RCHPlacementRecsBuilder: “recsForPlacements” builder
RCHStrategyRecsBuilder: “recsUsingStrategy” builder
RCHUserPrefsBuilder: “user/preferences” read/write builder
RCHUserProfileBuilder: “UserProfile” builder
RCHPersonalizeBuilder: Builder for personalize calls
RCHGetProductsBuilder: Builder for getProducts calls

Each builder has type-safe methods for setting relevant values and a “build” method that produces a map of key/value pairs to be sent as the final request. There are also helper methods for common use-cases that create pre-configured builders (see next section).

Builder “Helper” Methods

The RCHSDK class contains several “factory” methods that vend pre-configured request builders for common API use-cases. These methods are separated into two groups, one for fetches and one for tracking. The former includes requests that expect responses such as recommended products, while the latter includes tracking requests that are essentially fire and forget.

Networking

The network operations performed by this SDK are at this time, not diverse enough to warrant inclusion of any third-party libraries such as AFNetworking. All calls at this time are HTTP GET, all payloads are JSON, and there are only a handful of endpoints and paths. In the future, more granular, REST-style API changes might warrant the introduction of such a library. With that said, some sub-components of AFNetworking are used for utility-style tasks such as creating properly encoded query parameters and managing network reachability.

Session Configuration

The SDK uses its own instance of NSURLSession to perform all network operations. In this way, the SDK’s network traffic is not handled in the same operation queue as the containing app’s, allowing for fine-grained session configuration specific only to the SDK traffic.

The session is configured via the RCHAPIClientConfig class. This class includes all relevant authentication information as well as helper methods for creating pre-configured NSURLSessionconfiguration.

API Client

The RCHAPIClient is the workhorse of the SDK. It handles all API interactions at the HTTP-level, consuming request information, asynchronously executing HTTP calls, and responding with parsed domain objects. It is possible to create a standalone instance of this class, but more advisable to use the defaultClient found on the RCHSDK class.

Requests

API requests originate from request builders (see above) as raw NSDictionary objects and are passed to one of the sendRequest variants in RCHAPIClient.

Each request dictionary contains two sub dictionaries underkRCHAPIBuilderParamRequestParameters, representing HTTP parameters to be sent directly as part of the request, and kRCHAPIBuilderParamRequestInfo, representing metadata for the request such as path, response parser, and auth. type.

Response

A response parser for a given request can be specified via the request info dictionary discussed in the previous section. Parser objects must conform to the RCHAPIResponseParser protocol and typically deserialize JSON objects into domain-specific model objects. There are default parsers present for all API paths currently supported and they are automatically specified by the path-specific builders.

Connectivity

In low or no network scenarios, for the majority of calls, the SDK does not queue or retry failed requests. If no network is present and concretely detectable, requests will not be attempted at all and appropriate errors will be reported to calling code.

The exception to this rule is for click tracking, in which case failed requests are queued in memory only and retried upon network restoration. See the trackClick method on RCHAPIClient for more information.

Logging

The SDK logs to console via NSLog and is configurable with the standard log levels (TRACE, DEBUG, INFO, WARN, ERROR, OFF). By default, logging is set to OFF, so as to not incur logging overhead for production releases. The RCHLog class is the location in which all logging logic lives.

Error conditions and handling

Runtime Errors

All SDK calls that make remote requests provide error feedback as part of completion handlers. Furthermore, a best effort has been made to ensure that any SDK thrown exceptions prevent the hosting app from crashing while still maintaining integrity of the SDK. See RCHErrors for a list of possible error codes.

API Response Validation

Despite the fact that the API is stable and well-documented, assumptions are not made as per the presence of fields in API responses. Expected fields are validated and calls fail gracefully in the face of unexpected API behavior.

Input Validation

All assumptions regarding SDK inputs (arguments passed to SDK methods by the parent app) are validated directly and handled accordingly. If the method consumes an error handler, the handler is invoked with an appropriate error code, otherwise the operation is aborted and error is logged.

Security

All SDK requests are performed over HTTPS by default and include API authentication parameters to ensure the maximum level of security. In situations where the API supports it, OAuth 1.0 is used to sign requests. The SDK does not store any data to disk, therefore on-disk encryption is not a concern at this time.