Swiftagram: A Swift repository from sbertix

Swiftagram is a wrapper for Instagram Private API, written entirely in (modern) Swift.

Instagram's official APIs, both the Instagram Basic Display API and the Instagram Graph API — available for Creator and Business accounts alone, either lack support for the most mundane of features or limit their availability to a not large enough subset of profiles.

In order to bypass these limitations, Swiftagram relies on the API used internally by the Android and iOS official Instagram apps, requiring no API token, and allowing to reproduce virtually any action a user can take. Please just bear in mind, as they're not authorized for external use, you're using them at your own risk.

What's SwiftagramCrypto?

Relying on encryption usually requires specific disclosure, e.g. on submission to the App Store.

Despite Swiftagram, as all libraries relying on unathorized third-party APIs, cannot be considered App Store safe, we still value separating everything depending on encryption into its owen target library, we call SwiftagramCrypto. Keep in mind features like BasicAuthenticator, a non-visual Authenticator, or KeychainStorage, the safe and preferred way to store Secrets, or even the ability to post on your feed and upload stories are SwiftagramCrypto only.

Please check out the docs to find out more.

Status

You can find all changelogs directly under every release, and if you care to be notified about future ones, don't forget to subscribe to our Telegram channel.

What's next?

Milestones, issues, as well as the WIP dashboard, are the best way to keep updated with active developement.

Feel free to contribute by sending a pull request. Just remember to refer to our guidelines and Code of Conduct beforehand.

Installation

Swift Package Manager (Xcode 11 and above)

Select File/Swift Packages/Add Package Dependency… from the menu.
Paste https://github.com/sbertix/Swiftagram.git.
Follow the steps.
Add SwiftagramCrypto together with Swiftagram for the full experience.

Why not CocoaPods, or Carthage, or ~~blank~~?

Supporting multiple dependency managers makes maintaining a library exponentially more complicated and time consuming.
Furthermore, with the integration of the Swift Package Manager in Xcode 11 and greater, we expect the need for alternative solutions to fade quickly.

Targets

Swiftagram depends on ComposableRequest, an HTTP client originally integrated in Swiftagram.
It supports Combine Publishers and caching Secrets, through ComposableStorage, out-of-the-box.
SwiftagramCrypto, depending on Swiftchain and a fork of SwCrypt, can be imported together with Swiftagram to extend its functionality, accessing the safer KeychainStorage and encrypted Endpoints (e.g. Endpoint.Friendship.follow, Endpoint.Friendship.unfollow).

Usage

Check out our Examples or visit the (auto-generated) documentation for Swiftagram and SwiftagramCrypto to learn about use cases.

Authentication

Authentication is provided through conformance to the Authenticator protocol, which, on success, returns a Secret containing all the cookies needed to sign an Endpoint's request.

The library comes with two concrete implementations.

WebView-based

Authenticator.Group.Visual is a visual based Authenticator, relying on a WKWebView in order to log in the user. As it's based on WebKit, it's only available for iOS 11 (and above) and macOS 10.13 (and above).

Example

import UIKit

import Swiftagram

/// A `class` defining a view controller capable of displaying the authentication web view.
class LoginViewController: UIViewController {
    /// The completion handler.
    var completion: ((Secret) -> Void)? {
        didSet {
            guard oldValue == nil, let completion = completion else { return }
            // Authenticate.
            DispatchQueue.main.asyncAfter(deadline: .now()) {
                // We're using `Authentication.keyhcain`, being encrypted,
                // but you can rely on different ones.
                Authenticator.keychain
                    .visual(filling: self.view)
                    .authenticate()
                    .sink(receiveCompletion: { _ in }, receiveValue: completion)
                    .store(in: &self.bin)
            }
        }
    }

    /// The dispose bag.
    private var bin: Set<AnyCancellable> = []
}

And then you can use it simply by initiating it and assining a completion handler.

let controller = LoginViewController()
controller.completion = { _ in /* do something */ }
// Present/push the controller.

Basic

Authenticator.Group.Basic is a code based Authenticator, supporting 2FA, defined in SwiftagramCrypto: all you need is a username and password and you're ready to go.

Example

import SwiftagramCrypto

/// A retained dispose bag.
/// **You need to retain this.**
private var bin: Set<AnyCancellable> = []

// We're using `Authentication.keyhcain`, being encrypted,
// but you can rely on different ones.
Authenticator.keychain
    .basic(username: /* username */,
           password: /* password */)
    .authenticate()
    .sink(receiveCompletion: {
            switch $0 {
            case .failure(let error):
                // Deal with two factor authentication.
                switch error {
                case Authenticator.Error.twoFactorChallenge(let challenge):
                    // Once you receive the challenge,
                    // ask the user for the 2FA code
                    // then just call:
                    // `challenge.code(/* the code */).authenticate()`
                    // and deal with the publisher.
                    break
                default:
                    break
                }
            default:
                break
            }
          }, 
          receiveValue: { _ in /* do something */ })
    .store(in: &self.bin)
}

Caching

Caching of Secrets is provided through its conformacy to ComposableStorage's Storable protocol.

The library comes with several concrete implementations of Storage.

TransientStorage should be used when no caching is necessary, and it's what Authenticators default to when no Storage is provided.
UserDefaultsStorage allows for faster, out-of-the-box, testing, although it's not recommended for production as private cookies are not encrypted.
KeychainStorage, part of ComposableRequestCrypto, (preferred) stores them safely in the user's keychain.

Request

How can I bypass Instagram "spam" filter, and make them believe I'm not actually a bot?

In older versions of Swiftagram we let the user set a delay between the firing of a request, and its actual dispatch. This would eventually just slow down implementations, doing close to nothing to prevent misuse.

Starting with 5.0, we're now directly exposing URLSessions to final users, so you can build your own implementation.

Swiftagram defines a static URLSession (URLSession.instagram) fetching one resource at a time. Relying on this is the preferred way to deal with Instagram "spam" filter.

// A valid secret.
let secret: Secret = /* the authentication response */
// A **retained** collection of cancellables.
var bin: Set<AnyCancellable> = []

// We're using a random endpoint to demonstrate 
// how `URLSession` is exposed in code. 
Endpoint.user(secret.identifier)
    .unlock(with: secret)
    .session(.instagram)    // `URLSession.instagram` 
    .sink(receiveCompletion: { _ in }, receiveValue: { print($0) })
    .store(in: &bin)

What about cancelling an ongoing request?

Once you have a stream Cancellable, just call cancel on it or empty bin.

// A valid secret.
let secret: Secret = /* the authentication response */
// A **retained** collection of cancellables.
var bin: Set<AnyCancellable> = []

// We're using a random endpoint to demonstrate 
// how `Deferrable` is exposed in code. 
Endpoint.user(secret.identifier)
    .unlock(with: secret)
    .session(.instagram) 
    .sink(receiveCompletion: { _ in }, receiveValue: { print($0) })
    .store(in: &bin)
    
// Cancel it.
bin.removeAll()

How do I deal with pagination and pagination offsets?

Easy. Assuming you're fetching a resource that can actually be paginated…

// A valid secret.
let secret: Secret = /* the authentication response */
// A **retained** collection of cancellables.
var bin: Set<AnyCancellable> = []

// We're using a random endpoint to demonstrate 
// how `PagerProvider` is exposed in code. 
Endpoint.user(secret.identifier)
    .posts
    .unlock(with: secret)
    .session(.instagram)
    .pages(.max, delay: 1)  // Exhaust all with `.max`
                            // or pass any `Int` to limit
                            // pages.
                            // You can omit `delay`, in that
                            // case pages will be fetched 
                            // one immediately after the other.
    .sink(receiveCompletion: { _ in }, receiveValue: { print($0) })
    .store(in: &bin)

PagerProvider also supports an offset, i.e. the value passed to its first iteration, and a rank (token) in same cases, both as optional parameters in the pages(_:offset:)/pages(_:offset:rank:) method above.

Special thanks

Massive thanks to anyone contributing to TheM4hd1/SwiftyInsta, dilame/instagram-private-api and ping/instagram_private_api, for the inspiration and the invaluable service to the open source community, without which there would likely be no Swiftagram today.

sbertix/Swiftagram