SwiftInstagram Logo

Platforms Swift 4.0 Travis Documentation License

CocoaPods compatible Carthage compatible Swift Package Manager


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.2'

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 "AnderGoig/SwiftInstagram" ~> 1.0.2

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.2")
    ]
)

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 command if 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 the SwiftInstagram.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 the Embedded Binaries section.

  • You will see two different SwiftInstagram.xcodeproj folders each with two different versions of the SwiftInstagram.framework nested inside a Products 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 the Embedded 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.

Info.plist

Authentication - SwiftInstagram docs

let api = Instagram.shared

// Login
api.login(navController: navigationController!, redirectURI: "YOUR REDIRECTION URI GOES HERE", success: {
    // Do your stuff here ...
}, failure: { error in
    print(error)
})

// Returns whether a session is currently available or not
let _ = api.isSessionValid()

// Logout
api.logout()

You can also specify the login permissions with the optional scopes parameter. By default, it is set to basic access, however, you can request multiple scopes at once:

api.login(navController: ..., scopes: [.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: 5, success: { (mediaSet) in
    // Do your stuff here ...
}, failure: { (error) in
    print(error.localizedDescription)
})

Users - SwiftInstagram docs - Official docs

api.user(_ userId: String, success: SuccessHandler<InstagramUser>? = default, failure: FailureHandler? = default)
api.recentMedia(fromUser userId: String, maxId: String = default, minId: String = default, count: Int = default, success: SuccessHandler<[InstagramMedia]>? = default, failure: FailureHandler? = default)
api.userLikedMedia(maxLikeId: String = default, count: Int = default, success: SuccessHandler<[InstagramMedia]>? = default, failure: FailureHandler? = default)
api.search(user query: String, count: Int = default, success: SuccessHandler<[InstagramUser]>? = default, failure: FailureHandler? = default)

Relationships - SwiftInstagram docs - Official docs

api.userFollows(success: SuccessHandler<[InstagramUser]>? = default, failure: FailureHandler? = default)
api.userFollowers(success: SuccessHandler<[InstagramUser]>? = default, failure: FailureHandler? = default)
api.userRequestedBy(success: SuccessHandler<[InstagramUser]>? = default, failure: FailureHandler? = default)
api.userRelationship(withUser userId: String, success: SuccessHandler<InstagramRelationship>? = default, failure: FailureHandler? = default)
api.follow(user userId: String, success: SuccessHandler<InstagramRelationship>? = default, failure: FailureHandler? = default)
api.unfollow(user userId: String, success: SuccessHandler<InstagramRelationship>? = default, failure: FailureHandler? = default)
api.approveRequest(fromUser userId: String, success: SuccessHandler<InstagramRelationship>? = default, failure: FailureHandler? = default)
api.ignoreRequest(fromUser userId: String, success: SuccessHandler<InstagramRelationship>? = default, failure: FailureHandler? = default)

Media - SwiftInstagram docs - Official docs

api.media(withId id: String, success: SuccessHandler<InstagramMedia>? = default, failure: FailureHandler? = default)
api.media(withShortcode shortcode: String, success: SuccessHandler<InstagramMedia>? = default, failure: FailureHandler? = default)
api.searchMedia(lat: Double = default, lng: Double = default, distance: Int = default, success: SuccessHandler<[InstagramMedia]>? = default, failure: FailureHandler? = default)

Comments - SwiftInstagram docs - Official docs

api.comments(fromMedia mediaId: String, success: SuccessHandler<[InstagramComment]>? = default, failure: FailureHandler? = default)
api.createComment(onMedia mediaId: String, text: String, failure: FailureHandler? = default)
api.deleteComment(_ commentId: String, onMedia mediaId: String, failure: FailureHandler? = default)

Likes - SwiftInstagram docs - Official docs

api.likes(inMedia mediaId: String, success: SuccessHandler<[InstagramUser]>? = default, failure: FailureHandler? = default)
api.like(media mediaId: String, failure: FailureHandler? = default)
api.unlike(media mediaId: String, failure: FailureHandler? = default)

Tags - SwiftInstagram docs - Official docs

api.tag(_ tagName: String, success: SuccessHandler<InstagramTag>? = default, failure: FailureHandler? = default)
api.recentMedia(withTag tagName: String, maxTagId: String = default, minTagId: String = default, count: Int = default, success: SuccessHandler<[InstagramMedia]>? = default, failure: FailureHandler? = default)
api.search(tag query: String, success: SuccessHandler<[InstagramTag]>? = default, failure: FailureHandler? = default)

Locations - SwiftInstagram docs - Official docs

api.location(_ locationId: String, success: SuccessHandler<InstagramLocation>? = default, failure: FailureHandler? = default)
api.recentMedia(forLocation locationId: String, maxId: String = default, minId: String = default, success: SuccessHandler<[InstagramMedia]>? = default, failure: FailureHandler? = default)
api.searchLocation(lat: Double = default, lng: Double = default, distance: Int = default, facebookPlacesId: String = default, success: SuccessHandler<[InstagramLocation]>? = default, failure: FailureHandler? = default)

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 CONTRIBUTING guidelines.

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

https://github.com/AnderGoig/SwiftInstagram