Add tutorial on subscriptions to match Android (#2072)

* Remove bits from under construction that are going to be handled with blog posts, update versions * Get rid of fragments and cache, bring over android subscriptions stuff * this is actually part 9 on iOS * bring over screenshots from Android tutorial * Correct link * Update everything for iOS * update index and link from prior step to include subscriptions * Fix link to subscriptions * add missing image * fix borked link * be clearer about replacing the print statement * remove "unnecessary" quotation marks * add missing sentence, make image less ginormous * Fix direction I definitely know my left from my right! :woman-facepaming: Co-authored-by: Calvin Cestari <[email protected]> * add missing word Co-authored-by: Calvin Cestari <[email protected]>
apollographql · Dec 20, 2021 · 95ee510 · 95ee510
1 parent 4d8b5bb
commit 95ee510
Show file tree

Hide file tree

Showing 12 changed files with 205 additions and 81 deletions.
diff --git a/docs/gatsby-config.js b/docs/gatsby-config.js
@@ -35,7 +35,8 @@ module.exports = {
             'tutorial/tutorial-pagination',
             'tutorial/tutorial-detail-view',
             'tutorial/tutorial-authentication',
-            'tutorial/tutorial-mutations'
+            'tutorial/tutorial-mutations',
+            'tutorial/tutorial-subscriptions'
           ],
           Usage:[
             'downloading-schema',

diff --git a/docs/source/tutorial/images/explorer_authentication_header.png b/docs/source/tutorial/images/explorer_authentication_header.png
diff --git a/docs/source/tutorial/images/explorer_subscription_success.png b/docs/source/tutorial/images/explorer_subscription_success.png
diff --git a/docs/source/tutorial/images/explorer_subscriptions_listening.png b/docs/source/tutorial/images/explorer_subscriptions_listening.png
diff --git a/docs/source/tutorial/images/explorer_tripsbooked_initial.png b/docs/source/tutorial/images/explorer_tripsbooked_initial.png
diff --git a/docs/source/tutorial/images/explorer_tripsbooked_renamed.png b/docs/source/tutorial/images/explorer_tripsbooked_renamed.png
diff --git a/docs/source/tutorial/images/schema_tripsBooked_definition.png b/docs/source/tutorial/images/schema_tripsBooked_definition.png
diff --git a/docs/source/tutorial/images/screenshot_trip_booked.png b/docs/source/tutorial/images/screenshot_trip_booked.png
diff --git a/docs/source/tutorial/tutorial-fragments-and-cache.md b/docs/source/tutorial/tutorial-fragments-and-cache.md
diff --git a/docs/source/tutorial/tutorial-introduction.md b/docs/source/tutorial/tutorial-introduction.md
@@ -4,9 +4,9 @@ title: "0. Introduction"
 
 Welcome! This tutorial demonstrates adding the Apollo iOS SDK to an app to communicate with a GraphQL server. It is confirmed to work with the following tools:
 
-- Xcode 13.0
-- Swift 5.5
-- Apollo iOS SDK 0.49.1
+- Xcode 13.2
+- Swift 5.6
+- Apollo iOS SDK 0.50.0
 
 The tutorial assumes that you're using a Mac with Xcode installed. It also assumes some prior experience with iOS development.
 
@@ -20,9 +20,7 @@ This tutorial takes you through building an app to "book a seat" on any of the r
 * Code generation
 * Queries and mutations
 * Error handling
-* Query watching [🚧 UNDER CONSTRUCTION 🚧]
-* File uploads [🚧 UNDER CONSTRUCTION 🚧]
-* Subscriptions [🚧 UNDER CONSTRUCTION 🚧]
+* Subscriptions
 
 A pre-built GraphQL server is provided for your app to execute operations against. 
 

diff --git a/docs/source/tutorial/tutorial-mutations.md b/docs/source/tutorial/tutorial-mutations.md
@@ -349,4 +349,4 @@ self.loadLaunchDetails(forceReload: true)
 
 Run the application. When you book or cancel a trip, the application will fetch the updated state and update the UI with the correct state. When you go out and back in, the cache will be updated with the most recent state, and the most recent state will display. 
 
-This works well, but it could be more efficient. In the next section (🤞 coming soon 🤞), you'll learn more about how to get details in a reusable fashion and how to work with the cache directly.
+In the next section, you'll learn how to use [subscriptions](/tutorial/tutorial-subscriptions/) with the Apollo client. 
diff --git a/docs/source/tutorial/tutorial-subscriptions.md b/docs/source/tutorial/tutorial-subscriptions.md
@@ -0,0 +1,198 @@
+---
+title: "9. Write your first subscription"
+---
+
+In this section, you will use subscriptions to get notified whenever someone books a flight 🚀! [Subscriptions](https://graphql.org/blog/subscriptions-in-graphql-and-relay/) allow you to be notified in real time whenever an event happens on your server. The [fullstack backend](https://apollo-fullstack-tutorial.herokuapp.com) supports subscriptions based on [WebSockets](https://en.wikipedia.org/wiki/WebSocket).
+
+
+## Write your subscription
+
+Open your [Sandbox](https://studio.apollographql.com/sandbox/explorer?endpoint=https%3A%2F%2Fapollo-fullstack-tutorial.herokuapp.com) back up, click on the Schema tab at the far left. In addition to `queries` and `mutations`, you will see a third type of operations, `subscriptions`. Click on subscriptions to see the `tripsBooked` subscription:
+
+<img alt="The definition of tripsBooked in the schema" class="screenshot" src="images/schema_tripsBooked_definition.png"/>
+
+This subscription doesn't take any argument and returns a single scalar named `tripsBooked`. Since you can book multiple trips at once, `tripsBooked` is an `Int`. It will contain the number of trips booked at once or -1 if a trip has been cancelled.
+
+Click the play button to the far right of `tripsBooked` to open the subscription in Explorer. Open a new tab, then check the `tripsBooked` button to have the subscription added:
+
+<img alt="The initial definition of the TripsBooked subscription" class="screenshot" src="images/explorer_tripsbooked_initial.png"/>
+
+Again, rename your subscription so it's easier to find:
+
+<img alt="The subscription after rename" class="screenshot" src="images/explorer_tripsbooked_renamed.png"/>
+
+Click the Submit Operation button, and your subscription will start listening to events. You can tell it's up and running because a panel will pop up at the lower left where subscription data will come in:
+
+<img alt="The UI showing that it's listening for subscription updates" class="screenshot" src="images/explorer_subscriptions_listening.png"/>
+
+## Test your subscription
+
+Open a new tab in Explorer. In this new tab, add code to book a trip like on [step 8](tutorial-mutations), but with a hard-coded ID:
+
+```graphql
+mutation BookTrip {
+  bookTrips(launchIds: ["93"]){
+    message
+  }
+}
+```
+
+Do not forget to include the authentication header. At the bottom of the Sandbox Explorer pane where you add operations, there's a `Headers` section:
+
+<img alt="Adding a login token to explorer" class="screenshot" src="images/explorer_authentication_header.png"/>
+
+Click the Submit Operation button. If everything went well, you just booked a trip! At the top of the right panel, you'll see the success JSON for your your `BookTrip` mutation, and below it, updated JSON for the `TripsBooked` subscription:
+
+<img alt="Subscription success in Explorer" class="screenshot" src="images/explorer_subscription_success.png"/>
+
+Continue booking and/or canceling trips, you will see events coming in the subscription panel in real time. After some time, the server might close the connection and you'll have to restart your subscription to keep receiving events.
+
+## Add the subscription to the project
+
+Now that your subscription is working, add it to your project. Create an empty file named `TripsBooked.graphql` next to your other GraphQL files and paste the contents of the subscription. The process is similar to what you've already done for queries and mutations:
+
+```graphql:title=TripsBooked.graphql
+subscription TripsBooked {
+  tripsBooked
+}
+```
+
+Build your project, and the subscription will be picked up and added to your `API.swift` file. 
+
+## Configure your ApolloClient to use subscriptions
+
+In `Network.swift`, you'll need to set up a transport which supports subscriptions in addition to general network usage. In practice, this means adding a `WebSocketTransport` which will allow real-time communication with your server. 
+
+First, at the top of the file, add an import for the **ApolloWebSocket** framework to get access to the classes you'll need:
+
+```swift:title=Network.swift
+import ApolloWebSocket
+```
+
+Next, in the lazy declaration of the `apollo` variable, immediately after `transport` is declared, set up what you need to add subscription support to your client: 
+
+```swift:title=Network.swift
+// 1
+let webSocket = WebSocket(url: URL(string: "wss://apollo-fullstack-tutorial.herokuapp.com/graphql")!)
+
+// 2
+let webSocketTransport = WebSocketTransport(websocket: webSocket)
+
+// 3
+let splitTransport = SplitNetworkTransport(uploadingNetworkTransport: transport,
+                                                   webSocketNetworkTransport: webSocketTransport)
+
+// 4       
+return ApolloClient(networkTransport: splitTransport, store: store)
+```
+
+What's happening here? 
+
+1. You've created a web socket with the server's web socket URL - `wss://` is the protocol for a secure web socket.
+2. You've created a `WebSocketTransport`, which allows the Apollo SDK to communicate with the web socket. 
+3. You've created a `SplitNetworkTransport`, which can decide whether to use a web socket or not automatically, with both the `RequestChainNetworkTransport` you had previously set up, and the `WebSocketTransport` you just set up. 
+4. You're now passing the `splitTransport` into the `ApolloClient`, so that it's the main transport being used in your `ApolloClient`.  
+
+Now, you're ready to actually use your subscription!
+
+## Display a view when a trip is booked/cancelled
+
+In `LaunchesViewController`, add a new variable just below `activeRequest` to hang on to a reference to your subscription so it doesn't get hammered by ARC as soon as it goes out of scope:
+
+```swift:title=LaunchesViewController.swift
+private var activeSubscription: Cancellable?
+```
+
+Next, just above the code for handling Segues, add code for starting and handling the result of a subscription:
+
+```swift:title=LaunchesViewController.swift
+// MARK: - Subscriptions
+
+private func startSubscription() {
+          activeSubscription = Network.shared.apollo.subscribe(subscription: TripsBookedSubscription()) { result in
+            switch result {
+            case .failure(let error):
+                self.showAlert(title: "NetworkError",
+                               message: error.localizedDescription)
+            case .success(let graphQLResult):
+                if let errors = graphQLResult.errors {
+                    self.showAlertForErrors(errors)
+                } else if let tripsBooked = graphQLResult.data?.tripsBooked {
+                    self.handleTripsBooked(value: tripsBooked)
+                } else {
+                    // There was no data and there were no errors, do nothing.
+                }
+            }
+        }
+    }  
+}
+
+private func handleSubscriptionEvent() {
+   print("Trips booked: \(value)")
+}
+```
+
+Finally, add a line to `viewDidLoad` which actually starts the subscription: 
+
+```swift:title=LaunchesViewController.swift
+override func viewDidLoad() {
+    super.viewDidLoad()
+    self.startSubscription()
+    self.loadMoreLaunchesIfTheyExist()
+}
+```
+
+Build and run your app and go back to Sandbox Explorer, and select the tab where you set up the `BookTrip` mutation. Book a new trip while your app is open, you'll see a log print out: 
+
+```
+Trips booked: 1
+```
+
+Cancel that same trip, and you'll see another log: 
+
+```
+Trips booked: -1
+```
+
+Now, let's display that information in a view! Replace the `print` statement in `handleTripsBooked` with code to use the included `NotificationView` to show a brief alert at the bottom of the screen with information about a trip being booked or cancelled: 
+
+```swift:title=LaunchesViewController.swift
+private func handleTripsBooked(value: Int) {
+        var message: String
+        switch value {
+        case 1:
+            message = "A new trip was booked! 🚀"
+        case -1:
+            message = "A trip was cancelled! 😭"
+        default:
+            self.showAlert(title: "Unexpected value",
+                           message: " Subscription returned unexpected value: \(value)")
+            return
+        }
+
+        NotificationView.show(in: self.navigationController!.view,
+                              with: message,
+                              for: 4.0)
+    }
+```
+
+Build and run the application to your simulator, then use Studio to send bookings and cancellations again, and your iOS app should see some shiny new notifications pop up: 
+
+<img alt="A new trip was booked (rocket)" class="screenshot" src="images/screenshot_trip_booked.png" width="300"/>
+
+And you've done it! You've completed the tutorial. 
+
+## More resources
+
+There are way more things you can do with the Apollo iOS SDK, and the rest of this documentation includes info on more advanced topics like:
+
+- Using [fragments](/fragments/)
+- Working with [custom scalars](/fetching-queries/#notes-on-working-with-custom-scalars)
+- [Caching](/caching/)
+
+Feel free to ask questions by either [opening an issue on our GitHub repo](https://github.com/apollographql/apollo-ios/issues), or [joining the community](http://community.apollographql.com/new-topic?category=Help&tags=mobile,client).
+
+And if you want dig more and see GraphQL in real-world apps, you can take a look at these open source projects using Apollo iOS:
+
+* https://github.com/GitHawkApp/GitHawk
+* [open a PR if you have an example app that should be here!]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -349,4 +349,4 @@ self.loadLaunchDetails(forceReload: true)

		Run the application. When you book or cancel a trip, the application will fetch the updated state and update the UI with the correct state. When you go out and back in, the cache will be updated with the most recent state, and the most recent state will display.

		This works well, but it could be more efficient. In the next section (🤞 coming soon 🤞), you'll learn more about how to get details in a reusable fashion and how to work with the cache directly.
		In the next section, you'll learn how to use [subscriptions](/tutorial/tutorial-subscriptions/) with the Apollo client.