Swift Package Index

Swiftagram

https://github.com/sbertix/Swiftagram.git

A modern Swift wrapper for Instagram Private API.


Compatibility

  • 4.2.10 and main
    5.3
    5.2
    5.1
    5.0
    4.2
  • 5.0.0-beta.2
    5.3
    5.2
    5.1
    5.0
    4.2
  • 4.2.10, 5.0.0-beta.2, and main
    iOS
    macOS(Intel)
    macOS(ARM)
    Linux
    tvOS
    watchOS

Swift codecov Telegram iOS macOS tvOS watchOS

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

push GitHub release (latest by date)

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)

  1. Select File/Swift Packages/Add Package Dependency… from the menu.
  2. Paste https://github.com/sbertix/Swiftagram.git.
  3. Follow the steps.
  4. 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.

  • Swiftagram depends on ComposableRequest, an HTTP client originally integrated in Swiftagram., and it's the core library.
    It supports Combine Publishers out of the box.

  • SwiftagramCrypto, depending on ComposableRequestCrypto 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 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.

WebViewAuthenticator

WebViewAuthenticator 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).

import UIKit
import WebKit

import ComposableRequest
import ComposableRequestCrypto
import Swiftagram

/// A `class` defining a `UIViewController` displaying a `WKWebView` used for authentication.
final class LoginViewController: UIViewController {
    /// Any `ComposableRequest.Storage` used to cache `Secret`s.
    /// We're using `KeychainStorage` as it's the safest option.
    let storage = KeychainStorage()
    /// A valid `Client`. We're relying on the `default` one.
    let client = Client.default

    /// The web view.
    var webView: WKWebView? {
        didSet {
            oldValue?.removeFromSuperview() // Just in case.
            guard let webView = webView else { return }
            webView.frame = view.bounds     // Fill the parent view.
            // You should also deal with layout constraints or similar here…
            view.addSubview(webView)        // Add it to the parent view.
        }
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        // Authenticate using any `Storage` you want (`KeychainStorage` is used as an example).
        // `storage` can be omitted if you don't require `Secret`s caching.
        // `client` can be omitted and the default once will be used.
        WebViewAuthenticator(storage: storage,
                             client: client) { self.webView = $0 }
            .authenticate {
                switch $0 {
                    case .failure(let error): print(error.localizedDescription)
                    default: print("Login succesful.")
                }
            }
        }
    }
}

BasicAuthenticator

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

import ComposableRequest
import ComposableRequestCrypto
import Swiftagram
import SwiftagramCrypto

/// Any `ComposableRequest.Storage` used to cache `Secret`s.
/// We're using `KeychainStorage` as it's the safest option.
let storage = KeychainStorage()
/// A valid `Client`. We're relying on the `default` one.
let client = Client.default

/// Authenticate.
BasicAuthenticator(storage: storage,    // Optional. No storage will be used if omitted.
                   client: client,      // Optional. Default client will be used if omitted.
                   username: /* username */,
                   password: /* password */)
    .authenticate {
        switch $0 {
        case .failure(let error):
            // Please check out the docs to find out how to deal with 2FA.
            print(error.localizedDescription)
        default: print("Login successful.")
        }
    }

Caching

Caching of Secrets is provided through conformance to the Storage protocol in ComposableRequest.

The library comes with several concrete implementations.

  • 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?

Just set the default waiting time in the Requester to something greater than 0.

import ComposableRequest
import Swiftagram
import SwiftagramCrypto

// Somewhere in your code, for instance in your `AppDelegate`, set a new `default` `Requester`.
// `O.5` to `1.5` seconds is a long enough time, usually.
// `Requester.instagram` deals about it for you.
Requester.default = .instagram

Or just create a custom Requester and pass it to every single request you make.

What if I wanna know the basic info about a profile?

All you need is the user identifier and a valid Secret.

let identifier: String = /* the profile identifier */
let secret: Secret = /* the authentication response */

// Perform the request.
Endpoint.User.summary(for: identifier)
    .unlocking(with: secret)
    .task {
        // Do something here.
    })
    .resume() // Strongly referenced by default, no need to worry about it.

What about cancelling an ongoing request?

Easy!

let secret: Secret = /* the authentication response */

// Perform the request.
let task = Endpoint.Friendship.following(secret.id)
    .unlocking(with: secret)
    .task(maxLength: 10,
          onComplete: { _ in },
          onChange: { _ in  
            // Do something here.
    })
    .resume() // Exhaust 10 pages of followers.

// Cancel it.
task?.cancel()

What about loading the next page?

Just resume it once more. If it's still fetching, nothing's gonna happen. But if it's not and there are still more pages to be fetched, a new one will be requested.

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.