Skip to content

Upgrading ​

No longer maintained by hand (owner decision, 2026-10-31: «отменяю оба правила, нам нужна автоматизация для этого из конвенциональных коммитов»; the automation for it is still in the backlog). The entries below are history, kept as written.

This page is the release-by-release record of the Simulator: what you change in your program when you move to a newer version. Versions follow one rule: a major version only for a large change to the Simulator's own core, a minor version for a breaking change that Instagram's remote API forces, a patch for a fix. Read every minor release between your version and the one you install.

Two things hold for every upgrade:

  • Stored sessions: see Keep a session. A checkpoint from release 4.11.0 or later starts in any later release, by launch or by a resume: the import keeps the app build the snapshot declares (a session saved on 222 sends the 222 user agent and build number) and fills only the fields the snapshot omits from the release's presented build.
  • A snapshot saved by any release from 4.0.3 on restores. A field that cannot be understood is dropped and logged instead of failing the restore.

4.15 ​

  • A display field of a screen's data or of a decoded answer is T | undefined. A schema states only the fields the library itself acts on; every other field is a display field, wrapped in Shown, and reads as undefined when it is absent, null or of another type — a drifted answer never fails the call or the screen enter. Read a display field as field ?? fallback; a field the library decides on — an id, a cursor — stays required and its type is unchanged. This release sweeps the search results' Accounts tab, the typeahead's dictionaries and the search field's recent accounts, and the Explore tab's recent-searches answer; the remaining screen and decode schemas keep their shape until their own sweep.
  • The Android pushToken option is removed. An Android device registers its own push token, and a caller's token is never sent; AndroidApp({ pushToken }), AndroidIgpapi.install({ pushToken }) and launch({ pushToken }) are type errors. Delete the option. iOS keeps pushToken for the APNs token Apple issues.
  • AndroidPushRegister and AndroidPushRegisterInput are no longer exported. The launch registers the device itself; delete a call to it.
  • The Pigeon building blocks only log. pigeonSendEvents is removed and pigeonSendInfraBatches is renamed emitPigeonInfraBatches; the process's one sender delivers what they logged. Log events with emitPigeonEvents, begin the session with emitPigeonInfraBatches, and call FlushTelemetry where your program must wait for the upload.
  • AnalyticsSend is no longer a member of the runtime surface. A service set built from AndroidRuntimeServices or IosRuntimeServices no longer provides it; stop requiring it and call FlushTelemetry where the program must wait for the upload.
  • perfClientTti and igTimeSpentScreenTime take the measured duration — perfClientTti({ durationMs }), igTimeSpentScreenTime({ sessionLengthSec }) — instead of drawing one at random. Pass the time your program measured.
  • MobileTelemetryState no longer holds events; the events are the device's (MobileDeviceState.telemetry.pending). TakeTelemetry returns queued events whose payload is JSON text (read it with queuedTelemetryPayloadOf), and RestoreTelemetry takes the channel first. Read the device's queue.
  • LoginHomepageHandle no longer has openEmailCode(), openApproveFromAnotherDevice() and openMethodPicker(). logIn takes them itself when the login hands off to the email code, the approval on another device or the two-factor method picker. Call logIn(credentials) and read the screen it answers instead of calling the transition.
  • An edge a screen's action takes after the person's input is declared in the definition's actionEdges table, beside actions; actionEdge(member) and the ActionEdge type are removed. Move each actionEdge(opens(…)) out of actions into actionEdges as the plain opens(…), and keep calling it from the action as openNext(self, state)(…).
  • VoiceAttachmentMessage requires its waveform, and the photo and the voice message no longer carry body. Pass waveform (measure it with voiceWaveformOf or pass your own samples), and stop reading body on these two types: the form is compose's.
  • The app's own restrictions are gone: the server decides. MediaRepostTextTooLongError, checkRepostText and MEDIA_REPOST_TEXT_MAX_LENGTH are removed (a repost text of any length is sent), and RepostNoteEditorUnavailableError, DirectGroupNameUnavailableError and MediaRepostTextNotAcceptedError are removed (the screens open and the server decides). Drop their handlers and calls; a refusal reaches you as its typed error — MediaRepostTextRejectedError or the core's RequestError.
  • A reaction names the tray's emoji. react() takes { emoji } and DirectReaction is { emoji: DirectReactionEmoji }, one of ❤, 😂, 😮, 😢, 😡 and 👍. message.react('like') becomes message.react({ emoji: '❤' }).
  • DirectEditMessage is the 451 GraphQL mutation and reads its answer. originalMessageClientContext is renamed offlineThreadingId and is optional, and the call resolves to the edit's value, failing with DirectEditMessageRejectedError when Instagram refused it or GraphqlRootFieldMissingError when the answer carries no result. Pass the message's client_context as offlineThreadingId and answer the two errors.
  • DirectThreadDeleteItem has no isSshMode (the 451 delete form carries no is_ssh_mode). Drop the argument.
  • DirectBroadcastFormParts carries the caller's sendSilently, isShhMode, isXTransportForward and extras, and a compose returns its fields through withBroadcastOptions. Wrap the fields a custom compose returns in withBroadcastOptions(parts, fields).
  • A PigeonContext you build yourself changed. sessionId is familyId, hmacTokens is authTokens (the hmac_ttl token is hmacTtlToken), identityRequest, samplingChecksum and configChecksum are required, and PigeonChecksum.timestamp is text. Rename the two fields, pass identityRequest: false and { timestamp: '0', hash: '' } when the upload is not a session's own, and write a checksum's timestamp as a string. A platform that provides its own MobileAppLifecycle adds foregroundCount, its count of foreground moments (return 0 when it models none).
  • A follow no longer reloads the profile's suggested-users rail. follow() answers the visit's suggested rows, and ProfileFollowAnswer.backgroundFailures is empty; ProfileReachedFrom gains { kind: 'recent' } for a profile opened from the search field's Recent list. A switch over ProfileReachedFrom gains the recent case, and a caller that wants the header's rail calls openSuggestedUsers().
  • reactionMessage's reactionActionSource defaults to emoji_tray, the message menu's source (a double tap on a message sends nothing in the 451 app). Pass reactionActionSource: 'double_tap' to send the old form.

4.14 ​

  • Every id is a string, in every response type and every input. An id that named an entity — a user, a media, a comment, a thread, an item, a story, a location, a hashtag, an audio, a broadcast — was a number in about 340 response types, or string | number in the inputs and some responses; it is string everywhere now, whatever its length, and the library reads a number under an id key as its exact text. The inputs that took string | number take string, so a program that passes a number gets a type error. Keep ids as strings and compare them as strings (media.user.pk === '555', not === 555), replace Number(user.pk) with the text itself, pass String(id) where you held a number, and read a stored list of ids as string[]; convert at the one place that needs a number (BigInt(id) for a long one). A zero the server writes under an id key is '0', and '0' is truthy: check emptiness with === '0'. The readers return text for ids too: parseJson, parseNdjson, jsonWithLongIdsAsText, fromJsonText, a typed error's body and a screen item's raw.
  • MediaOembedResponse describes only what the library reads: every field is optional, and a field the answer adds is kept. Check a field for undefined before using it.
  • WebChallengeInfo is the page as the server answered it (unknown), and the web challenge step's challengeType is string | undefined; webChallengeTypeOf(challenge) reads the type.
  • A telemetry id keeps every digit, and MobileTelemetryEventSchema is MobileTelemetryEventTrailSchema. The trail reader reads a stored payload of plain JSON; the live event is the MobileTelemetryEvent type. Rename the schema you use.
  • DirectRecipientPickerScreen's search(query) answers { recipients, threads } instead of the recipients array. Read .recipients for the people and .threads where the search shows conversations.
  • DirectBroadcastMessage.body is optional, and a message may lay its own form out. DirectBroadcastMessage.compose (with DirectBroadcastFormParts) returns the whole form and the broadcast adds nothing around it; DirectBroadcastInput.extras adds fields after the navigation chain. A message type with a body keeps it; a message that lays out every field returns compose.
  • DirectThreadInput's send_attribution is a closed set — inbox, inbox_new_message, direct_thread_creation_omnipicker, message_button. Pass one of the four.
  • DirectThreadDetails is a sum on the thread's kind: a one-to-one thread carries its peer's peer_user_id and peer_user_fbid, a group its first participant's lead_user_id. Narrow on is_group before reading a peer's field.
  • The oldest TypeScript a user may have is 7. TypeScript 5.9 support is gone; the published declarations are checked with TypeScript 7.

4.13 ​

  • effect is a peer dependency. @igpapi/core, @igpapi/mobile, @igpapi/android, @igpapi/ios and @igpapi/pigeon-nest declare effect (^4.0.6) as a peer instead of carrying their own copy, so your project and the packages share one copy of Effect. Install it beside the platform package: npm install @igpapi/android [email protected] (or pnpm add …, yarn add …). npm 7 and later and pnpm 8 and later install a missing peer by themselves; Yarn only warns, and the import fails until effect is a dependency of your project. A project that already depends on [email protected] or a later 4.x changes nothing. The install page has the registry setup for each package manager.
  • A launch returns as soon as the feed is on screen. The rest of the start-up runs on in the process's background; the call still waits for it before the app closes, and checkpoint() and ExportSnapshot wait for it before they read. A session-fatal answer to it rejects the call with the same typed error (The app process).
  • MobileProcessBackground changed shape: startTimer, armedTimers and restoreTimers are gone. A program that waited for the process's background work uses awaitMobileProcessBackground, which fails with the session-fatal error the background met.
  • New: totpCodeOf(secret) returns the code an authenticator app shows, so a headless login can submit it (Log in, with two-factor). share() of a post, a Reel or a story reports the media's short code when Instagram's answer carries it.

4.12 ​

  • A list whose items are a tagged union is open. An item of a kind the Simulator does not model is kept as an explicit unknown item and never fails the screen. The types of these lists are wider, so TypeScript code that read a member without narrowing, or switched exhaustively, stops compiling. TypeaheadResult and TypeaheadRow, and TimelineFeedResponseFeedItemsItem and FeedTimelineEntry, have one more member (the typeahead result's discriminant is kind: 'unknown'; the timeline entry has type: 'unknown'; the typeahead row has __typename: 'unknown'). Narrow before you read a member, and add a branch for the unknown one.
  • effect is the stable 4.0.6. Programs that compose the Simulator's services with their own Effect code use Context.Service and Context.Reference where the beta had ServiceMap.
  • Three exports of @igpapi/core/mobile changed with the snapshot restore: legacySnapshotNetworkOf takes the stored value, settleDeviceAdsOptOut takes the stored value instead of the session, and settleSessionNavigation is removed. A caller passes the stored value or drops the call: MobileSnapshotSchema reads the stored fields itself.

4.11: program is main ​

  • Rename program to main. The callback option of AndroidIgpapi.install, launch, resumeSilently, resumeFromBackground, resumeByReentering, and of IosIgpapi.install and launch, is main. A caller that still passes program fails at run time with TypeError: main is not a function. The type names follow: AndroidIgpapiProgram is AndroidIgpapiMain, and IosIgpapiProgram is IosIgpapiMain.
  • main never receives a challenge. Code that caught IgCheckpointError inside main and called OpenChallenge moves into an otherwise branch (Answer a challenge with otherwise). OpenChallenge stays for a program that composes AndroidApp itself. IosIgpapi has the rename alone, because iOS has no screens.
  • Publish through the screens. The one-call posting bricks are removed (TimelinePhotoPost, AlbumPost, ClipPost, UploadPhoto, UploadVideo and their inputs). Use FeedTimelineScreen.openCreation(mode), pick, edit, share, in a launched process (Publishing).
  • openCreation(mode) takes 'post' | 'story' | 'reel' and answers exactly that mode's first screen.
  • PostingPhotoInput and PostingVideoInput lose takenAt and folder; the device's media store answers them through the gallery's second argument.
  • PostingMusicSearchResult is a union with a kind discriminant ('track' or 'originalAudio'), and PostingMusicProduct has kind: 'story-sticker' and kind: 'reel'.
  • ClipMusicOptions loses assetId, clusterId, songName, artistName and sessionId; all are derived from track. Pass track (a ReelSongTrack) and the two volumes.
  • jsonBigString is jsonWithLongIdsAsText. It returns unknown; rename the import and read the value through the Simulator's schemas.
  • ScreenNotOnTopError.reason: covered only while the screen is still open under another; a handle whose screen was closed, opened again or replaced is navigation-moved.
  • A checkpoint written by an earlier release is refused; log in again and take a new one.

The pages of this site are the README files of the repository. The API reference is generated from the source.