Published on

Introducing ReleaseNotesKit

This is ReleaseNotesKit, a brand new, elegant, and extremely simple way to present the recent version’s release notes to your users. ReleaseNotesKit uses the iTunesSearchAPI to access information about the app. It has methods for caching data, presenting once on a version change, accessing just the data, and presenting the sheet without any preconditions.

Configuration

ReleaseNotesKit can be initialized using:

ReleaseNotesKit.shared.setApp(with: "1548193451") //Replace with your app's ID

Ideally, you'd like to set this once per app launch. Therefore, a good place to set this code would be in your App's AppDelegate file.

Usage

Note: Before accessing any of ReleaseNotesKit’s methods, you have to initialize the shared instance with the app ID. Failure to do this will throw an assertion failure during DEBUG and will do nothing during PROD.

ReleaseNotesKit can provide you both the data in a Swift Struct and also present a sheet with the data in a pre-styled format.

Just the data

To access just the data call parseCacheOrFetchNewData. This method has a default parameter precondition that is set to false by default. For simply accessing the data, precondition can remain false. This check is useful for our subsequent usage types.

ReleaseNotesKit.shared.parseCacheOrFetchNewData { result in
    switch result {
    case .success(let response):
        print(response.releaseNotes)
    case .failure(let error):
        print(error.rawValue)
    }
}

The completion returns a Swift Result type with ITunesLookupResult for the success case and ReleaseNotesError in case of failure. ReleaseNotesError is defined in the following way:

enum ReleaseNotesError: String, Error {
    case malformedURL
    case malformedData
    case parsingFailure
    case noResults
}

Let’s quickly go over each of these cases and what they mean so that it’ll be easy for you to handle it in your code:

  • malformedURL: The iTunesSearchAPI’s URL failed to get constructed. This will never happen if a properly formatted App ID is passed in the singleton’s setApp method.
  • malformedData: The data that is returned from the iTunesSearchAPI is corrupted or not readable.
  • parsingFailure: JSONDecoder failed to parse the data into ITunesLookup.
  • noResults: There was no available results returned for this particular appID. Please check if the appID is correct or if the app is brand new, please wait for a few hours for AppStore to index your app.

Presenting the ReleaseNotesView for the first time

ReleaseNotesKit can present the ReleaseNotesView when the version changes. To present the sheet once per version update, you can call presentReleaseNotesViewOnVersionChange.

ReleaseNotesKit.shared.presentReleaseNotesViewOnVersionChange()

There’s two checks that happen in this method:

guard let lastVersionSheetShownFor = UserDefaults.standard.string(forKey: "lastVersionSheetShownFor") else { ... }

In this first case, we check if the UserDefaults string for lastVersionSheetShownFor is nil which can happen when the user has installed the app for the first time.

result.currentVersion != Bundle.main.releaseVersionNumber || String(result.appID ?? 0) != self.appID
  • Current version stored in the cached response != The installed app's version
  • The cached lookup's appID is different than the set app ID.

Presenting ReleaseNotesView without Preconditions

It is possible to present the ReleaseNotesView without any version check preconditions. To call this, simply call presentReleaseNotesView. You may choose to pass a controller: UIViewController or let it be nil and the framework will access the UIApplication’s top view controller and present the ReleaseNotesView on that top controller.

ReleaseNotesKit.shared.presentReleaseNotesView(in: self)

Or, without the controller to present.

ReleaseNotesKit.shared.presentReleaseNotesView()

Testing

There has been some manual testing done by myself. However, I am looking for contributions that will add a good testing suite. If you’re willing, please feel free to open a PR!

Like the framework?

If you like ReleaseNotesKit please consider buying me a coffee 🥰

Contribution

Contributions are always welcome. Please follow the following convention if you’re contributing:

NameOfFile: Changes Made One commit per feature For issue fixes: #IssueNumber NameOfFile: ChangesMade

License

This project is licensed under the MIT License - see the LICENSE file for details

Apps using ReleaseNotesKit

If you’re using ReleaseNotesKit in your app please open a PR to edit this Readme. I’ll be happy to include you in this list :D