moltin / ios-sdk

Swift SDK for the Moltin eCommerce API

Elastic Path Commerce Cloud iOS Swift SDK

A simple to use iOS/tvOS/watchOS SDK to help get you off the ground quickly and efficiently with your Elastic Path Commerce Cloud written in Swift.

📚 API reference — 📚 Elastic Path Commerce Cloud

Requirements

• iOS 10.0+ / tvOS 10.0+ / watchOS 3.0+
• Swift 4.0+

Installation

Cocoapods

Add the following to your Podfile:

pod 'Moltin', '~> 3.1.2'

Or, quickly try out our examples:

pod try Moltin

Carthage

Add the following to your Cartfile:

github "Moltin/ios-sdk" ~> 3.1.2

Swift Package Manager

Add the following to your dependencies value in Package.swift:

dependencies: [
    .package(url: "https://github.com/moltin/ios-sdk.git", from: "3.1.2")
]

Usage

Making a request

let moltin = Moltin(withClientID: "<your client ID>")

moltin.product.all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

moltin.product.get("<product ID>") { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

moltin.product.tree { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Checking out & Payment

Paying for a cart is a two step process in Moltin.

First, check out your cart, which will return you an order:

self.moltin.cart.checkout(
    cart: ...,
    withCustomer: ...,
    withBillingAddress: ...,
    withShippingAddress: ...) { (result) in
    switch result {
        case .success(let order):
            ...
        default: break
    }
}

Now that you have an order, you can pay for your order. Moltin providers several gateways for you to use:

• Stripe
• BrainTree
• Adyen
• Manual

Once you've chosen your payment gateway, you can fulfil one of Moltin's PaymentMethod's:

let paymentMethod = StripeToken(withStripeToken: ...)

You can then use this payment method to pay for an order:

self.moltin.cart.pay(
    forOrderID: order.id,
    withPaymentMethod: paymentMethod) { (result) in
    ...
}

Config

The basic way to set up the Moltin SDK is to create an instance of the Moltin class with your client ID and optionally the locale of the application. However, if you'd like to change additional details of the SDK, such as the URL of your Moltin instance, you can do so by passing in MoltinConfig.

let moltin = Moltin(withClientID: ...) // Takes Locale.current

let moltin = Moltin(withClientID: ..., withLocale: ...)

let config = MoltinConfig(
    clientID: ...,
    scheme: ...,
    host: ...,
    version: ...,
    locale: ...)

let moltin = Moltin(withConfiguration: config)

Or:

let config = MoltinConfig.default(
    withClientID: ...,
    withLocale: ...)

let moltin = Moltin(withConfiguration: config)

Available Resources

• Brands
• Carts
• Categories
• Collections
• Currencies
• Files
• Flows
• Fields
• Entries
• Products

Authentication

Authentication is handled silently for you as part of the SDK. The SDK will cache credentials to ensure that it is not making unnecessary requests.

The iOS SDK only supports Implicit authentication currently.

Filtering

Operations

• Filter
• Sort
• Offset / Limit
• Include

Filter

moltin.product.filter(operator: .eq, key: "name", value: "ProductName").all {
   ...
}

Sort

moltin.product.sort("order").all {
   ...
}

moltin.product.sort("-order").all {
   ...
}

Offset / Limit

moltin.product.limit(10).offset(20).all {
    ...
}

Include

moltin.product.include([.mainImage, .files]).all {
    ...
}

Combining Operations

moltin.product.sort("-name").include([.mainImage]).limit(20).all {
   ...
}

Flows

If you've implemented a custom field on a resource by using flows, you can cast this to a type of your choice by type-hinting your result, so long as this type conforms to Codable:

moltin.product.all { (result: Result<PaginatedResponse<[MyCustomProduct]>>) in
    switch result {
        case .success(let response):
            print(response.data) // [MyCustomProduct]
        case .failure(_):
            break
    }
}

moltin.product.get(forID: "<your ID>") { (result: Result<MyCustomProduct>) in
    switch result {
    case .success(let response):
        print(response) // MyCustomProduct
    case .failure(_):
        break
    }

We recommend ensuring that your types extend from our base types for safety, then you implement the required init(from decoder: Decoder):

class MyCustomProduct: moltin.Product {
    let author: Author

    enum ProductCodingKeys : String, CodingKey {
        case author
    }

    required init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: ProductCodingKeys.self)
        self.author = try container.decode(Author.self, forKey: .author)
        try super.init(from: decoder)
    }
}

This will allow you to add additional types as you need, but ensures the base type, such as product, is still parsed correctly.

Examples

The Swift SDK is a community-supported software development kit for Elastic Path Commerce Cloud (formerly Moltin). The following examples show you how to use the SDK to make requests to the Commerce Cloud APIs.

For details about the endpoints, objects, and responses, see the Elastic Path Commerce API Reference.

• Basics
  • Includes
  • Pagination
  • Filtering
  • Sorting
  • Tokens
• Currency
• Products
• Brands
• Categories
• Collections
• Carts
• Customers
• Payments

Basics

Includes

Examples of using include with resources. For more information, see Includes.

Include category products

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.category.include([.products]).get(forID: id) { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Include product main_image

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.product.include([.main_image]).all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Multiple includes

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.product.include([.main_image, .category]).all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Pagination

Examples of using pagination with resources. For more information, see Pagination.

Get all categories, two per page

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.limit(2).all {
  // Do something
}

Get products 21-30

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.limit(10).offset(20).all {
  // Do something
}

Filtering

Examples of using different filter operators. For more information, see Filtering.

The eq operator

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .eq, key: "commodity_type", value: "digital").all {
  // Do something
}

The like operator - A string begins with a specified value

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .like, key: "sku", value: "SHOE_DECK_*").all {
  // Do something
}

The like operator - A string contains a specified value

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .like, key: "sku", value: "*_DECK_*").all {
  // Do something
}

The like operator - A string ends with a specified value

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .like, key: "sku", value: "*_RED").all {
  // Do something
}

Chaining multiple operators

Caution: This feature is currently in Beta and you should expect it to change.

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product
  .filter(operator: .eq, key: "commodity_type", value: "physical")
  .sort("created_at")
  .all {
  // Do something
}

Sorting

Examples of using sort with resources. For more information, see Sorting.

Sort products by created_at in ascending order

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.sort("created_at").all {
  // Do something
}

Sort products by created_at in descending order

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.sort("-created_at").all {
  // Do something
}

Tokens

Get an implicit access token

An implicit token can be thought of as a Read only token.

let moltin = Moltin(withClientID: "<your client ID>")

Currency

Get a currency

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.currency.get(forID: id) { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Get all currencies

let moltin = Moltin(withClientID: "<your client ID>")
moltin.currency.all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Products

Get all products

let moltin = Moltin(withClientID: "<your client ID>")
self.moltin.product.include([.mainImage]).all { (result: Result<PaginatedResponse<[moltin.Product]>>) in
   switch result {
       case .success(let response):
            DispatchQueue.main.async {
                self.products = response.data ?? []
            }
        case .failure(let error):
            print("Products error", error)
        }
    }
}

Get all products that belong to a category

let moltin = Moltin(withClientID: "<your client ID>")
moltin.product.filter(operator: .eq, key: "category.id", value: "xxxx").all {
response in
// Do something
}

Get a product

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.product.get(forID: id) { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Brands

Get all brands

let moltin = Moltin(withClientID: "<your client ID>")
moltin.brand.all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Get a brand

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.brand.get(forID: id) { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Categories

Get all categories

let moltin = Moltin(withClientID: "<your client ID>")
moltin.category.all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Get a category

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.category.get(forID: id) { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Get the categories tree

let moltin = Moltin(withClientID: "<your client ID>")
moltin.category.tree { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Collections

Get all collections

let moltin = Moltin(withClientID: "<your client ID>")
moltin.collection.all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Get a collection

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.collection.get(forID: id) { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Carts

Get a cart

let moltin = Moltin(withClientID: "<your client ID>")
self.moltin.cart.get(forID: AppDelegate.cartID, completionHandler: { (result) in
    switch result {
        case .success(let result):
            DispatchQueue.main.async {
                print("Cart:", result)
                }
            case .failure(let error):
                print("Cart error:", error)
            }
    })

Get cart items

let moltin = Moltin(withClientID: "<your client ID>")
let referenceId = 'XXXX'
self.moltin.cart.items(forCartID: referenceId) { (result) in
    switch result {
        case .success(let result):
            DispatchQueue.main.async {
                 print("Cart items:", result.data)
            }
            case .failure(let error):
                print("Cart error:", error)
            }
        }
    }

Add a product to a cart

let moltin = Moltin(withClientID: "<your client ID>")
let referenceId = 'XXXX'
let productId = 'XXXX'
let productQty = 'XXXX'
self.moltin.cart.addProduct(withID: productId , ofQuantity: productQty, toCart: referenceId, completionHandler: { (_) in
})

Add a promotion to a cart

let moltin = Moltin(withClientID: "<your client ID>")
let referenceId = 'XXXX'
self.moltin.cart.addPromotion(code, toCart: referenceId) { (result) in
    switch result {
        case .success(let status):
            DispatchQueue.main.async {
                print("Promotion: (status)")
            }
            default: break
            }
        }
}

Check out a cart

let moltin = Moltin(withClientID: "<your client ID>")
moltin.cart.checkout(
    cart: ...,
    withCustomer: ...,
    withBillingAddress: ...,
    withShippingAddress: ...) { (result) in
    switch result {
        case .success(let order):
            ...
        default: break
    }
}

Delete a cart

let moltin = Moltin(withClientID: "<your client ID>")
let referenceId = 'XXXX'
self.moltin.cart.deleteCart(referenceId, completionHandler: { (result)    in
    switch result {
        case .success(let result):
            print("Cart error:", result)
        case .failure(let error):
            print("Cart error:", error)
        }
})

Customers

Get a customer

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
moltin.customer.get(forID: id) { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Payments

Create a Stripe payment

let moltin = Moltin(withClientID: "<your client ID>")
let paymentMethod = StripeToken(withStripeToken: ...)
moltin.cart.pay(
    forOrderID: order.id,
    withPaymentMethod: paymentMethod) { (result) in
    ...
}

Create a manually authorize payment

let moltin = Moltin(withClientID: "<your client ID>")
let id = "XXXX"
let paymentMethod = ManuallyAuthorizePayment()
moltin.cart.pay(forOrderID: order.id, withPaymentMethod: paymentMethod) { (result) in
    switch result {
        case .success:
            print("Success")
        case .failure(let error):
            print(error)
    }
}

Further Documentation

Find more general documentation on the API docs.

Communication

• If you need help with the SDK or the platform, get in touch on the forum
• If you found a bug with the SDK, open an issue on GitHub
• If you have a feature request for the SDK, open an issue.
• If you want to contribute to the SDK, submit a pull request.

License

Moltin is available under the MIT license. See the LICENSE file for more info.

ios-sdk's Issues

Tableview: change from catagory to brand to product

A client has submitted a request for information:

Please could someone provide any information on this?

The v2 example molten app is completely broken.

The molten example app categories don't work correctly and neither does the checkout. Pretty much nothing works.

Consider Changing Class Prefix

Perhaps for version 2, you should re-consider the two-letter MT prefix. Generally Cocoa apps are encouraged to use a three-letter prefix to avoid clashes with system frameworks.

"Two-letter prefixes like these are reserved by Apple for use in framework classes." from https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Conventions.html

Carthage Support

Would like to see support for Carthage ;)

The SDK is not parsing CartRequest responses correctly

Issue Type

• Question
• Feature
• Bug
• Other Issue

Issue Description and Steps

Looks like the removeItem method is attempting to parse a Cart object, but the response is returning [CartItem]. Need to update the function to return this correctly.

Also worth looking into the other requests here to make sure they're correct

No Such Module 'Moltin'

I followed instruction and installed the pod file to my project. I open the workspace and clean and build it. I then try to import Moltin, but "no such module" is found. I created a bridging header containing the statement: "#import <Moltin/Moltin.h>". I have the compiling settings for objective c in build settings set to the bridging header I created. I've tried several solutions, but nothing works. Help with this issue would be greatly appreciated.

cart api

The cart api is not returning an array of product but a key value json. Shouldn't it be an array? How do you loop around products?

updating user

I'm trying to update the customer object but I get this error error = "You do not have access to the (write) customers scope"; and there's no way to change the permission scope for the customer.

How can I achieve this with the iOS sdk? Should I implement the API call by myself skipping the SDK?

Finding products by brand (SWIFT)

I am trying to find a subset of Product by brand.
However, I cannot find any examples of how to query by Product.brand.
I have tried the brand.title & brand.ID as the values but have been unsuccessful.

Moltin.sharedInstance().product.searchWithParameters(["brand": **?????**])

App Installation Failed

I'm sorry to say that the Moltin module is still not working. While version 3.0.6 fixed the problem with the import statement, the pod is still broken. Attached is a video of a clean Xcode project (seen to run successfully) and also a video of the Moltin pod added to it. After the Moltin pod is added, the import statement is read correctly but upon run the app fails to install. A quick response to this would be greatly appreciated as I'm trying my best to enjoy Moltin but there seems to be no end of problems with it.
Video 1 (Without Moltin): https://drive.google.com/file/d/1bIDsQqryrm-EGcHtumxY25-eHeTRLmdX/view?usp=sharing
Video 2 (With Moltin): https://drive.google.com/file/d/1czsb0rnhbrnE5WUe4BBM0_ngvfwI50jU/view?usp=sharing