marketcloud-swift-sdk

#####The official repository for Marketcloud iOS swift SDK (beta)

Marketcloud is a mobile-first e-commerce backend as a service. If you wish to use this SDK in order to build your own Android application, you have to subscribe to Marketcloud's program.

#Setup

Installation via Carthage

######Just follow these steps:

Install the last release of Carthage.pkg (https://github.com/Carthage/Carthage/releases)
Create your new Xcode project
Open the terminal, navigate to the root directory of your project (the directory that contains your .xcodeproj file)
Create an empty Cartfile with the touch command: touch Cartfile
open the file up in Xcode for editing (don't close your terminal!): open -a Xcode Cartfile
You will see an empty page. Just write github "Marketcloud/marketcloud-swift-sdk" and close it.
Return on your terminal and write carthage update --platform iOS or simply carthage update. If you see any warnings, ignore them for the moment. I will remove them in the next release!
Carthage will clone the repository and create a new .framework file for you. Just wait for a bit and when the operation is over close your terminal, open Xcode and your project and follow the last step of this tutorial..
Select your project in the Project Navigator. Select the target, choose the General tab at the top, and scroll down to the Linked Frameworks and Libraries section at the bottom. Open a Finder window and navigate to the Folder, then go to the Carthage -> Build -> iOS folder (you should be in a similar situation: /Carthage/Build/iOS Now, drag Marketcloud.framework into the Linked Frameworks and Libraries section in Xcode.

Confused? Click here for a .gif with with a similar situation http://cdn2.raywenderlich.com/wp-content/uploads/2015/06/carthage-settings.gif

Last (but not least...) On your application targets “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script with the following contents: /usr/local/bin/carthage copy-frameworks and add the paths to the frameworks you want to use under “Input Files”, e.g.:

$(SRCROOT)/Carthage/Build/iOS/Marketcloud.framework

This script works around an App Store submission bug triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving.

If you are still confused or this tutorial is not good enough for you, check this Carthage tutorial or the official Carthage Github page

If you need more informations, Check this out! (this last is the best in my opinion)

#THE SDK

Here you can find all the methods explained and a tutorial about how to work with the sdk

Are you in a hurry? Or maybe you just want to try yourself? Here's a playground with every method available to be tested -> Playground

If you managed to import the library via Carthage you could import the SDK with import Marketcloud

Then instantiate a Marketcloud object with var marketcloud = Marketcloud(key: "insert_your_public_key_here");

And.... you are good to go!

Products

marketcloud.getProducts() returns a NSDictionary with all the products in your store

marketcloud.getProducts(filter:[String: Any]) Use this method to filter the products.

Example:

var itemArray = [String: Any]()
itemArray.append(["Author":"Tolkien","Pages":"213"])

marketcloud.getProducts(itemArray)

returns a NSDictionary with all the products that match with the filters.

marketcloud.getProductById(id:Int) returns a NSDictionary with the informations about the product with that Id marketcloud.getProductById(id:String) same as before, but you can insert the Id as a String instead of an Integer

marketcloud.getProductsByCategory(id:Int) returns a NSDictionary with the informations about all the products belonging to that category marketcloud.getProductsByCategory(id:String) same as before, but you can insert the Id as a String instead of an Integer

Brands

marketcloud.getBrands() returns a NSDictionary with all the brands in your store

marketcloud.getBrandById(id:Int) returns a NSDictionary with the informations about the brand with that Id marketcloud.getBrandById(id:String) same as before, but you can insert the Id as a String instead of an Integer

Carts

marketcloud.createEmptyCart() creates a new cart and returns a NSDictionary with the informations about the new cart

marketcloud.getCart() !!!ONLY FOR LOGGED USERS!!! Returns a NSDictionary with the informations about the last user's cart

marketcloud.getCart(id:Int) Returns a NSDictionary with the informations about the cart with that Id marketcloud.getCart(id:String) same as before, but you can insert the Id as a String instead of an Integer

marketcloud.addToCart(id:Int, data:[Any]) 'id' is the cart's id, data:[Any] is an array with informations about the products Id and the quantity of the selected products

Example:

var itemArray = [Any]()
itemArray.append(["product_id":8762,"quantity":2])
itemArray.append(["product_id":8766,"quantity":3])

marketcloud.addToCart(idCart, data: itemArray)

A NSDictionary with the infos about the updated cart will be returned.

marketcloud.addToCart(id:String, data:[Any]) Same as before, but you can insert the Id as a String instead of an Integer

marketcloud.updateCart(id:Int, data:[Any]) This method is similar to the 'addToCart' one. Its purpose is to insert a 'data' array with informations about a product that still exists in the cart and to update its quantity value. If the products didn't exist, it will be added (exactly like calling the 'addToCart' method). A NSDictionary with the infos about the updated cart will be returned. marketcloud.updateCart(id:String, data:[Any]) Same as before, but you can insert the Id as a String instead of an Integer

marketcloud.removeFromCart(id:Int, data:[Any]) This method needs the id of the cart and an array with the informations about the id of the product(s) you want to remove from the cart.

Example:

var itemArray = [Any]()
itemArray.append(["product_id":8762])
itemArray.append(["product_id":8766])

marketcloud.removeFromCart(idCart, data: itemArray)

Note that if the product is not in the cart, nothing will happen.

marketcloud.removeFromCart(id:String, data:[Any]) Same as before, but you can insert the Id as a String instead of an Integer.

Addresses

marketcloud.createAddress(datas:[String:Any]) !!!ONLY FOR LOGGED USERS!!! Creates a new address and returns a NSDictionary with the informations about the created address.

example:

let testAddress:[String:String] = ["email":"[email protected]","full_name": "alienFromOuterSpace","country" : "universe", "state": "LmaoLand", "city": "lmaoTown", "address1": "ayyy, 1", "postal_code": "123", "address2":"Lmao"]

marketcloud.createAddress(testAddress)

Accepted fields:

email [required]
full_name [required]
country [required]
state [required]
city [required]
address1 [required]
postal_code [required]
address2
phone_number
alternate_phone_number

marketcloud.getAddresses() !!!ONLY FOR LOGGED USERS!!! Returns a NSDictionary with the informations about the user's addresses

marketcloud.getAddress(id:Int) !!!ONLY FOR LOGGED USERS!!! Returns a NSDictionary with the informations about the selected address marketcloud.getAddress(id:String) !!!ONLY FOR LOGGED USERS!!! Same, but you can insert a String instead of an Integer

marketcloud.updateAddress(id:Int, datas:[String:Any]) !!!ONLY FOR LOGGED USERS!!! updates an address given its Id. Accepts an array in the same way as the createAddress one. Returns an NSDictionary with the information about the updated address

marketcloud.updateAddress(id:String, datas:[String:Any]) !!!ONLY FOR LOGGED USERS!!! Same, but you can insert a String instead of an Integer

marketcloud.removeAddress(id:Int) !!!ONLY FOR LOGGED USERS!!! removes an address given its Id marketcloud.removeAddress(id:String) !!!ONLY FOR LOGGED USERS!!! Same, but you can insert a String instead of an Integer

Users

marketcloud.createUser(datas:[String:Any]) Creates a new User. Accepts an array with the informations about the user. marketcloud.updateUser(datas:[String:Any], id:Int) Updates an existing User. Accepts an array with the informations about the user and the id of the user.

Example:

let testAddress:[String:String] = ["email":"[email protected]","name": "alienFromOuterSpace","password" : "universe"]
marketcloud.createUser(testAddress);

Accepted fields:

email [required]
name [required]
password [required]

Returns a NSDictionary with informations about the created user.

marketcloud.logIn(datas:[String:Any]) Use this method to perform a login for the current user.

Example:

let loginTest:[String:String] = ["email":"[email protected]", "password":"universe"]
marketcloud.logIn(loginTest)

Accepted fields:

email [required]
password [required]

Returns a NSDictionary with informations about the user.

After a successful login, headers will automatically change and all the operations from this point on will be performed as a logged user (es getCart(), get()). If you want to return to the 'non-logged' state you must use the logOut() method or re-initialize the marketcloud object. d marketcloud.logOut() logs out the current user (if logged in). Returns a NSDictionary with informations about the operation.

ORDERS

marketcloud.createOrder(shippingId:Int, billingId:Int, cartId:Int) confirms an order. This method needs a shipping Id, a billing address Id and the current cart Id.

Example

//suppose that '13320' is a valid address Id and 56000 a valid cart id
marketcloud.createOrder(13320, billingId: 13320, cartId: 56000)
//Note that the shipping and the billing address Ids could be different!

Returns a NSDictionary with informations about the order.

marketcloud.completeOrder(orderId:Int, stripeToken:String) .

This method completes an order and needs the order's id and a valid Stripe Token. Call it after createOrder() and when you have a valid Stripe Token (using Stripe's SDK).

Returns a NSDictionary with informations about the order.

##Currencies marketcloud.getCurrencies()

Returns a NSDictionary with informations about the actual currencies.

##Shippings marketcloud.getShippings()

Returns a NSDictionary with informations about the available shipping methods.

marketcloud.getShippingById(id:Int) Returns a NSDictionary with informations about a shipping method given its Id

marketcloud.getShippingById(id:String) Same as marketcloud.getShippingById(id:Int) but you can insert a String instead of a Int.

##Utils There are some useful methods that could help you in using the SDK.

marketcloud.utils.checkVarType(myVar:Any?) prints information about the variable type marketcloud.utils.stringBuilder(myVar:NSDictionary) converts a NSDictionary into a NSString marketcloud.utils.isValidJson(jsonObject:Any) returns true if the object is a valid Json marketcloud.utils.timeStamp() returns an UInt with the current timestamp

##Other

marketcloud.getKey() returns the actual publicKey marketcloud.userId() returns the actual user Id (-1 if user is not logged in) marketcloud.userId() returns the actual user token (returns an empty string if user is not logged in)

##PLAYGROUND

I strongly recommend to check the SDK's Playground. There are almost all methods explained, and you can test them in real time (there is a key with a sample store for testing purposes).

##Sample application

Sample Swift application using the SDK

HTTPS##

This SDK uses HTTPS for every communication with the API!

##LICENCE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License (see 'LICENCE.md' in the main project's directory).

###Additional

special thanks to JUST for the amazing HTTP library!
special thanks to Reachability.swift

marketcloud / marketcloud-swift-sdk Goto Github PK