A Swift wrapper for the Instagram API.
Requirements
- iOS 9.0+
- Xcode 9.0+
Installation
CocoaPods
CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:
$ gem install cocoapods
CocoaPods 1.1.0+ is required to build SwiftInstagram 1.0.0+.
To integrate SwiftInstagram into your Xcode project using CocoaPods, specify it in your Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!
pod 'SwiftInstagram', '~> 1.0.0'
Then, run the following command:
$ pod install
Carthage
Carthage is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.
You can install Carthage with Homebrew using the following command:
$ brew update
$ brew install carthage
To integrate SwiftInstagram into your Xcode project using Carthage, specify it in your Cartfile
:
github "SwiftInstagram/SwiftInstagram" ~> 1.0.0
Swift Package Manager
To use SwiftInstagram as a Swift Package Manager package just add the following in your Package.swift file.
import PackageDescription
let package = Package(
name: "HelloSwiftInstagram",
dependencies: [
.Package(url: "https://github.com/AnderGoig/SwiftInstagram.git", "1.0.0")
]
)
Manually
If you prefer not to use either of the aforementioned dependency managers, you can integrate SwiftInstagram into your project manually.
Git Submodules
- Open up Terminal,
cd
into your top-level project directory, and run the following commandif
your project is not initialized as a git repository:
$ git init
- Add SwiftInstagram as a git submodule by running the following command:
$ git submodule add https://github.com/AnderGoig/SwiftInstagram.git
$ git submodule update --init --recursive
Open the new
SwiftInstagram
folder, and drag theSwiftInstagram.xcodeproj
into the Project Navigator of your application’s Xcode project.It should appear nested underneath your application’s blue project icon. Whether it is above or below all the other Xcode groups does not matter.
Select the
SwiftInstagram.xcodeproj
in the Project Navigator and verify the deployment target matches that of your application target.Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the
Targets
heading in the sidebar.In the tab bar at the top of that window, open the
General
panel.Click on the
+
button under theEmbedded Binaries
section.You will see two different
SwiftInstagram.xcodeproj
folders each with two different versions of theSwiftInstagram.framework
nested inside aProducts
folder.It does not matter which
Products
folder you choose from.Select the
SwiftInstagram.framework
.And that’s it!
The
SwiftInstagram.framework
is automagically added as a target dependency, linked framework and embedded framework in a copy files build phase which is all you need to build on the simulator and a device.
Embeded Binaries
- Download the latest release from https://github.com/AnderGoig/SwiftInstagram/releases
- Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the
Targets
heading in the sidebar. - In the tab bar at the top of that window, open the
General
panel. - Click on the
+
button under theEmbedded Binaries
section. - Add the downloaded
SwiftInstagram.framework
. - And that’s it!
Usage
SwiftInstagram uses client side (implicit) authentication, so you must uncheck the option **Disable implicit OAuth**
from the Security tab of your Instagram client.
Also, copy the Client ID from your client and paste it inside your Info.plist
file with InstagramClientId
as the key.
Authentication - SwiftInstagram docs
let api = Instagram.shared
// Login
api.login(navController: navigationController!, redirectURI: "YOUR REDIRECTION URI GOES HERE") { (error) in
if let error = error {
print(error)
}
DispatchQueue.main.async {
self.navigationController?.popViewController(animated: true)
// Do your stuff here ...
}
}
// Returns whether a session is currently available or not
let _ = api.isSessionValid()
// Logout
let _ = api.logout()
You can also specify the login permissions with the optional parameter authScope
, by default, it is set to basic access. To request multiple scopes at once, simply separate the scopes by a +
.
api.login(navController: ..., authScope: "likes+comments", redirectURI: ... ) { }
Data retrieval
All of the following functions are very similar and straightforward, here’s an example of retrieving recent media:
let api = Instagram.shared
api.recentMedia(fromUser: "self", count: 3, completion: { (mediaSet, error) in
guard let mediaSet = mediaSet else {
print(error!.message)
return
}
// Do your stuff here ...
})
Users - SwiftInstagram docs - Official docs
api.user(_ userId: String, completion: @escaping (_ user: InstagramUser?, _ error: InstagramError?) -> Void)
api.recentMedia(fromUser userId: String, maxId: String = default, minId: String = default, count: Int = default, completion: @escaping (_ mediaSet: [InstagramMedia]?, _ error: InstagramError?) -> Void)
api.userLikedMedia(maxLikeId: String = default, count: Int = default, completion: @escaping (_ mediaSet: [InstagramMedia]?, _ error: InstagramError?) -> Void)
api.search(user query: String, count: Int = default, completion: @escaping (_ userSet: [InstagramUser]?, _ error: InstagramError?) -> Void)
Relationships - SwiftInstagram docs - Official docs
api.userFollows(completion: @escaping (_ userSet: [InstagramUser]?, _ error: InstagramError?) -> Void)
api.userFollowers(completion: @escaping (_ userSet: [InstagramUser]?, _ error: InstagramError?) -> Void)
api.userRequestedBy(completion: @escaping (_ userSet: [InstagramUser]?, _ error: InstagramError?) -> Void)
api.userRelationship(withUser userId: String, completion: @escaping (_ relationship: InstagramRelationship?, _ error: InstagramError?) -> Void)
api.follow(user userId: String, completion: @escaping (_ relationship: InstagramRelationship?, _ error: InstagramError?) -> Void)
api.unfollow(user userId: String, completion: @escaping (_ relationship: InstagramRelationship?, _ error: InstagramError?) -> Void)
api.approveRequest(fromUser userId: String, completion: @escaping (_ relationship: InstagramRelationship?, _ error: InstagramError?) -> Void)
api.ignoreRequest(fromUser userId: String, completion: @escaping (_ relationship: InstagramRelationship?, _ error: InstagramError?) -> Void)
Media - SwiftInstagram docs - Official docs
api.media(withId id: String, completion: @escaping (_ media: InstagramMedia?, _ error: InstagramError?) -> Void)
api.media(withShortcode shortcode: String, completion: @escaping (_ media: InstagramMedia?, _ error: InstagramError?) -> Void)
api.searchMedia(lat: Double = default, lng: Double = default, distance: Int = default, completion: @escaping (_ mediaSet: [InstagramMedia]?, _ error: InstagramError?) -> Void)
Comments - SwiftInstagram docs - Official docs
api.comments(fromMedia mediaId: String, completion: @escaping (_ comments: [InstagramComment]?, _ error: InstagramError?) -> Void)
api.createComment(onMedia mediaId: String, text: String, completion: @escaping (_ error: InstagramError?) -> Void)
api.deleteComment(_ commentId: String, onMedia mediaId: String, completion: @escaping (_ error: InstagramError?) -> Void)
Likes - SwiftInstagram docs - Official docs
api.likes(inMedia mediaId: String, completion: @escaping (_ users: [InstagramUser]?, _ error: InstagramError?) -> Void)
api.like(media mediaId: String, completion: @escaping (_ error: InstagramError?) -> Void)
api.unlike(media mediaId: String, completion: @escaping (_ error: InstagramError?) -> Void)
Tags - SwiftInstagram docs - Official docs
api.tag(_ tagName: String, completion: @escaping (_ tag: InstagramTag?, _ error: InstagramError?) -> Void)
api.recentMedia(withTag tagName: String, maxTagId: String = default, minTagId: String = default, count: Int = default, completion: @escaping (_ mediaSet: [InstagramMedia]?, _ error: InstagramError?) -> Void)
api.search(tag query: String, completion: @escaping (_ tags: [InstagramTag]?, _ error: InstagramError?) -> Void)
Locations - SwiftInstagram docs - Official docs
api.location(_ locationId: String, completion: @escaping (_ location: InstagramLocation?, _ error: InstagramError?) -> Void)
api.recentMedia(forLocation locationId: String, maxId: String = default, minId: String = default, completion: @escaping (_ mediaSet: [InstagramMedia]?, _ error: InstagramError?) -> Void)
api.searchLocation(lat: Double = default, lng: Double = default, distance: Int = default, facebookPlacesId: String = default, completion: @escaping (_ locations: [InstagramLocation]?, _ error: InstagramError?) -> Void)
Contributing
If you have feature requests or bug reports, feel free to help out by sending pull requests or by creating new issues. Please take a moment to review the guidelines written by Nicolas Gallagher:
Credits
SwiftInstagram is brought to you by Ander Goig and contributors to the project. If you’re using SwiftInstagram in your project, attribution would be very appreciated.
Companion libraries
SwiftInstagram uses keychain-swift by @evgenyneu to safely store the access token retrieved by the authentication process.
License
SwiftInstagram is released under the MIT license. See LICENSE for details.
Author
Ander Goig, goig.ander@gmail.com