Shopify Mobile Buy SDK for iOS

The GraphQL schema defines a Node interface with an id field. The SDK allows you to query any object by its ID using the .node(id:) method. However, because the result is returned as a generic node, you must cast it to the specific generated type (e.g., Storefront.Product) to access its properties. Incorrect casting will result in a runtime exception.

let id    = GraphQL.ID(rawValue: "gid://shopify/Product/123")
let query = Storefront.buildQuery { $0
    .node(id: id) { $0
        .onProduct { $0
            .id()
            .title()
        }
    }
}

// response: Storefront.QueryRoot
let product = response.node as! Storefront.Product

The completion handler for requests returns an optional Graph.QueryError.

Crucial: error and response are NOT mutually exclusive. A request can return both a non-nil error and a non-nil response. An error might represent a network issue (e.g., HTTP status code) or a GraphQL issue (e.g., invalid syntax).

Common error types include:

• .http(statusCode): Represents HTTP-level errors.
• .invalidQuery: Returns an array of Reason objects containing detailed debugging information (not intended for end-users).

let task = client.queryGraphWith(query) { response, error in
    if let response = response {
        // Do something
    } else {
        if let error = error, case .http(let statusCode) = error {
            print("Query failed. HTTP error code: \(statusCode)")
        }
    }
}
task.resume()

As of version 2025.1.0, the SDK uses a modified CalVer (Calendar Versioning) scheme: yyyy.mm.patch.

• The first two components (yyyy.mm) match the Shopify Storefront GraphQL API version.
• The third component (patch) corresponds to non-breaking bug fixes within an API version cycle.

Warning: Unlike SemVer, there may be breaking GraphQL schema changes between "minor" versions because they are tied to API release cycles.

You can enable retry or polling behavior for both queries and mutations by providing an optional RetryHandler.

Create a handler with a condition. If both handler.condition and handler.canRetry evaluate to true, the Client will continue executing the request. By default, retryHandler is nil and no retry behavior is provided.

let handler = Graph.RetryHandler<Storefront.QueryRoot>() { (query, error) -> Bool in
    if myCondition {
        return true // will retry
    }
    return false // will complete the request, either succeed or fail
}

The Mobile Buy SDK can be integrated into your iOS application using several dependency managers. Swift Package Manager is the recommended approach.

### Swift Package Manager
Follow Apple's guide for [adding a package dependency to your app](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app).

To install as a dynamic framework, follow these steps:

1. Add Buy as a git submodule:

   git submodule add git@github.com:Shopify/mobile-buy-sdk-ios.git

2. Update all submodules:
   ```bash
git submodule update --init --recursive

3. Drag Buy.xcodeproj into your application project.
4. Add Buy.framework target as a dependency in Build Phases > Target Dependencies.
5. Link Buy.framework in Build Phases > Link Binary With Libraries.
6. Copy the framework into the bundle: Create a New Copy Files Phase, set Destination to Frameworks, and add Buy.framework.
7. Import the module in your code using import Buy.

GraphQLSwiftGen is a Ruby-based code generator that requires Ruby version 2.1 or later.

It is recommended to include the repository as a git submodule:

$ git submodule https://github.com/Shopify/graphql_swift_gen.git

To manage dependencies, add the following to your application's Gemfile (assuming the submodule is in your project structure):

gem 'graphql_swift_gen', path: 'graphql_swift_gen'

Then run:

$ bundle

Important: The generated code depends on support/Sources/GraphQL.swift from the graphql_swift_gen repository. You must add this file to your Swift project along with the generated code.

Graph.Client is the network layer used to execute GraphQL query and mutation requests. It is built on top of URLSession and supports features like polling, retrying, and caching.

To initialize a client, you need your shop's .myshopify.com domain and your API key. You can optionally provide a URLSession for custom network configuration or a Locale to support translated content if your store uses multiple languages.

// Basic initialization
let client = Graph.Client(
	shopDomain: "shoes.myshopify.com",
	apiKey:     "dGhpcyBpcyBhIHByaXZhdGUgYXBpIGtleQ"
)

// Initializing a client to return translated content
let client = Graph.Client(
	shopDomain: "shoes.myshopify.com",
	apiKey:     "dGhpcyBpcyBhIHByaXZhdGUgYXBpIGtleQ",
        locale:     Locale.current
)