7. Write your first subscription
4m

Overview

Query and Mutation aren't the only types in —when we want real-time updates about server-side events, we'll need the third and final GraphQL type: the Subscription!

In this lesson, we will:

  • Write a to receive booking notifications
  • Enable ApolloClient with WebSocket support
  • Test the in-app

Apollo iOS and subscriptions

With subscriptions, we can get notifications about real-time events as they happen. We'll spend this last lesson of the course exploring how we can build a subscription operation to receive a notification when someone books a seat on a launch! 🚀

supports WebSockets and Multipart HTTP for . For this tutorial we'll use WebSockets.

Note: To learn more about Multipart HTTP, see Multipart HTTP protocol for GraphQL Subscriptions.

Let's create a subscription!

Open up Sandbox, or use the embedded Explorer in the collapsible section below.

Click on the Schema tab at the far left. In addition to queries and mutations, we'll find a third type, Subscription. Click on Subscription to see the tripsBooked :

https://studio.apollographql.com/sandbox/schema

Sandbox opened to the Schema page, with focus on the Subscription type. Its tripsBooked field is highlighted

This doesn't take any and returns a single named tripsBooked. Since we 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 in Explorer. Open a new tab, then check the tripsBooked button to have the added:

https://studio.apollographql.com/sandbox/explorer

Sandbox opened to the Explorer page, where a new subscription operation has been added

Again, we'll rename the so it's easier to find:

subscription TripsBooked {
  tripsBooked
}

Click the Submit button, and the will start listening to events. We can tell it's up and running because a panel will pop up at the lower right where subscription data will come in:

https://studio.apollographql.com/sandbox/explorer

The Explorer UI updated to show that a subscription has been submitted and Explorer is now listening for events

Test your subscription

Open a new tab in Explorer. In this new tab, add code to book a trip like in the previous lesson, but with a hard-coded ID:

mutation BookTrip {
  bookTrips(launchIds: ["93"]) {
    message
  }
}

Don't forget to include the authentication header! Make sure the Headers section in the Operation panel is populated with your token.

Authorization token
bWVAZXhhbXBsZS5jb20=

Click the Submit button. If everything went well, we've just booked a trip! At the top of the right panel, we'll see the success JSON for our BookTrip , and below it, updated JSON for the TripsBooked :

https://studio.apollographql.com/sandbox/explorer

The Explorer UI updated with a successfully booked trip event

Continue booking and/or canceling trips! We'll see events arriving in the 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 your project

Now that the is working, let's add it to the project. Create an empty file (don't add to the app target) named TripsBooked.graphql next to your other files and paste the contents of the . The process is similar to what we've already done for queries and :

TripsBooked.graphql
subscription TripsBooked {
  tripsBooked
}

Now run code generation in the terminal to generate the code for your .

Code generation command
./apollo-ios-cli generate

Keeping an eye on the RocketReserverAPI local package? We should see a new directory, called Subscriptions, was added!

Configure ApolloClient to use subscriptions

In Network.swift, we'll need to set up a transport which supports in addition to general network usage. In practice, this means adding a WebSocketTransport which will allow real-time communication with the server.

First, at the top of the file, we'll add an import for the ApolloWebSocket framework to get access to the classes we'll need:

Network.swift
import Foundation
import Apollo
import ApolloWebSocket

Next, in the lazy declaration of the apollo , immediately after transport is declared, we'll set up what we require to add support to the client:

Network.swift
private(set) lazy var apollo: ApolloClient = {
    let client = URLSessionClient()
    let cache = InMemoryNormalizedCache()
    let store = ApolloStore(cache: cache)
    let provider = NetworkInterceptorProvider(client: client, store: store)
    let url = URL(string: "https://apollo-fullstack-tutorial.herokuapp.com/graphql")!
    let transport = RequestChainNetworkTransport(interceptorProvider: provider, endpointURL: url)


    let webSocket = WebSocket(
        url: URL(string: "wss://apollo-fullstack-tutorial.herokuapp.com/graphql")!,
        protocol: .graphql_ws
    )


    let webSocketTransport = WebSocketTransport(websocket: webSocket)


    let splitTransport = SplitNetworkTransport(
        uploadingNetworkTransport: transport,
        webSocketNetworkTransport: webSocketTransport
    )


    return ApolloClient(networkTransport: splitTransport, store: store)
}()

What's happening here?

  1. We've created a WebSocket connection with the server's WebSocket URL - wss:// is the protocol for a secure WebSocket.
  2. We've created a WebSocketTransport, which allows the Apollo SDK to communicate with the web socket.
  3. We've created a SplitNetworkTransport, which can decide whether to use WebSocket or HTTP automatically, with both the RequestChainNetworkTransport we'd set up previously, and the WebSocketTransport we just set up.
  4. We're now passing the splitTransport into the ApolloClient, so that it's the main transport being used.

Now, we're ready to actually use our !

Use the subscription

To use the we created, go to LaunchListViewModel.swift and start by adding a new to hold the :

LaunchListViewModel.swift
@Published var launches = [LaunchListQuery.Data.Launches.Launch]()
@Published var lastConnection: LaunchListQuery.Data.Launches?
@Published var activeRequest: Cancellable?
var activeSubscription: Cancellable?
@Published var appAlert: AppAlert?
@Published var notificationMessage: String?

Now, replace the TODO in the startSubscription() method with the following code:

LaunchListViewModel.swift
func startSubscription() {
    activeSubscription = Network.shared.apollo.subscribe(subscription: TripsBookedSubscription()) { [weak self] result in
        guard let self = self else {
            return
        }


        switch result {
        case .success(let graphQLResult):
            if let tripsBooked = graphQLResult.data?.tripsBooked {
                self.handleTripsBooked(value: tripsBooked)
            }


            if let errors = graphQLResult.errors {
                self.appAlert = .errors(errors: errors)
            }
        case .failure(let error):
            self.appAlert = .errors(errors: [error])
        }
    }
}

Next, update the TODO in the init() method to the following:

LaunchListViewModel.swift
init() {
    startSubscription()
}

Notice in LaunchListView.swift there is already a line to handle displaying a view from the :

LaunchListView.swift
.notificationView(message: $viewModel.notificationMessage)

Test your subscription in-app

Build and run the application: now whenever a trip is booked or cancelled (from either in the app detail view or from ) we should see a small notification pop up at the bottom of the screen:

A subscription notification appearing in the UI after a trip is booked or cancelled

Practice

What types of features are GraphQL subscriptions useful for?
What protocols are supported in Apollo iOS for subscriptions?

Journey's end

Congratulations on completing the two-part and Swift series! You've successfully learned the basics of the Apollo iOS SDK to connect your Swift app to a . You have:

  • Downloaded a schema
  • Added code generation into your workflow
  • Written and executed queries and in and in your app
  • Learned how to handle errors
  • Used basic authentication
  • Implemented basic pagination
  • Worked with WebSockets to receive real-time updates

So, what's next? Keep your progress going! Check out these resources:

Feel free to ask questions by joining the Apollo community forums.

Thank you for choosing !

Previous

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.