InAppStory

A library for embedding stories into an application with customization.

Installation

InAppStory version	Build version	iOS version
1.21.2	2638	>= 10.0

Version of the library can be obtained from the parameter InAppStory.buildInfo

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate InAppStory into your Xcode project using CocoaPods, specify it in your Podfile:

use_frameworks!
pod 'InAppStory', :git => 'https://github.com/inappstory/ios-sdk.git', :tag => '1.21.2'

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate InAppStory into your Xcode project using Carthage, specify it in your Cartfile:

github "inappstory/ios-sdk" ~> 1.21.2

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. It is in early development, but InAppStory does support its use on supported platforms.

Once you have your Swift package set up, adding InAppStory as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/inappstory/ios-sdk.git", .upToNextMajor(from: "1.21.2"))
]

Manual installation

Download InAppStorySDK.xcframework from the repository. Connect in the project settings on the General tab.

Library import

Objective-C

#import <InAppStorySDK/InAppStorySDK.h>

Swift

import InAppStorySDK

Migration

from InAppStorySDK - v 1.8.x -> Migration guide to 1.9.0
from InAppStorySDK - v 1.9.x -> Migration guide to 1.10.0
from InAppStorySDK - v 1.10.x -> Migration guide to 1.11.0
from InAppStorySDK - v 1.14.x -> Migration guide to 1.15.0
from InAppStorySDK - v 1.15.x -> Migration guide to 1.16.0
from InAppStorySDK - v 1.x.x -> Migration guide to 1.21.0

InAppStory

The main singleton class for managing data and customizing the display of lists and the reader.

Initialization

Library Initialization is preferably carried out in AppDelegate:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool 
{
	InAppStory.shared.initWith(serviceKey: <String>, testKey: <String>, settings: <Settings?>)
	return true
}

serviceKey - service authorization key (<String>);
testKey - test authorization key in the service (<String>);
settings - configuration object (<Settings?> - optional).

Attention!
If you pass testKey, then the library will display the stories only in the "Moderation" status.

Methods

setTags(<Array<String>>) - replacing all tags;
addTags(<Array<String>>) - adding tags;
removeTags(<Array<String>>) - remove tags;
getWidgetStories(complete: (Array<WidgetStory>?) -> Void) - getting a list of stories for a widget;
showOnboardings(from target: <UIViewController>, delegate: <InAppStoryDelegate>, complete: @escaping (_ show: Boll) -> Void) - show onboarding reader, also see <InAppStoryDelegate>
onboardingPresent(controller presentingViewController: <UIViewController>, with transitionStyle: <UIModalTransitionStyle>) - serves for display of a custom controller over onboarding stories;
showSingle(with id: <String>, from target: <UIViewController>, delegate: <InAppStoryDelegate>, complete: @escaping (_ show: Bool) -> Void) - show single reader, also see <InAppStoryDelegate>
singleStoryPresent(controller presentingViewController: <UIViewController>, with transitionStyle: <UIModalTransitionStyle>) - serves for display of a custom controller over a single story;
closeReader(complete: () -> Void) - closing any story reader that showinng with a closure, complete is called after the reader is closed;
clearCache - clear all cache of library;
removeFromFavorite(with storyID: <String>) - remove story from favorites;
removeAllFavorites() - remove all favorites stories;

Parameters and properties

isReaderOpen - show that reader is open on screen or not nil in InAppStory.shared
favoritesCount - the number of favorite stories a user has;
isLoggingEnabled - displaying requests to the server in the console;
isEditorEnabled - moved to StoryView parametrs;
isEditorShowing - is editor current displaying; (InAppStoryUGC)
placeholders - personalization substitution list Dictionary<String, String>;
imagesPlaceholders - images personalization substitution list Dictionary<String, String>;
widgetStories - data for iOS widget.
sslPinningHashKeys - hashs of public keys for SSL-Pinning Array?

Customization

Customization of the appearance of the cells and the reader occurs through the singleton of the class InAppStory.shared:

List

coverQuality - quality of cover images in cells <Quality>;
showCellTitle - displaying story titles in a cell <Bool>;
cellFont - cell title font <UIFont>;
cellBorderColor - cell border color <UIColor>;
cellBorderRadius - radius of default cell borders <CGFloat>;
cellGradientEnabled - display shading on the bottom of the default cell <Bool>;
editorCellSettings - setting the cell view of the UGC editor <EditorCellProtocol>;

Goods widget

goodsCellMainTextColor - default goods item cell text color <UIColor>;
goodsCellDiscountTextColor - default goods item cell discount text color <UIColor>;
goodCellTitleFont - default goods item cell title font <UIFont>;
goodCellSubtitleFont - default goods item cell subtitle font <UIFont>;
goodCellPriceFont - default goods item cell price font <UIFont>;
goodCellDiscountFont - default goods item cell discount font <UIFont>;
goodsCloseBackgroundColor - close button background color <UIColor>;
goodsSubstrateColor - backround color under goods list <UIColor>;
refreshGoodsImage - images for refresh button <UIImage>;
goodsCloseImage - images for close button <UIImage>;
goodCell - custom cell, should implement the protocol <GoodsCellProtocol>;
goodsView - custom goods view, should inherit from <CustomGoodsView>;
goodsDelegateFlowLayout - should implement the protocol <GoodsDelegateFlowLayout>;

Reader

swipeToClose - closing the reader by swipe <Bool>;
overScrollToClose - closing the reader when scrolling through the last story <Bool>;
placeholderElementColor - slide preloader color <UIColor>;
placeholderBackgroundColor - slide preloader background color <UIColor>;
gamePlaceholderTint - default game loader tint color <UIColor>;
muted - mute/unmute the sound in the story <Bool>; (Details)
readerBackgroundColor - reader background color, by default black <UIColor>;
readerCornerRadius - corner radiof of stories cards, by default 16.0 <CGFloat>;
timerGradientEnable - enable gradient shadow under timers in story <Bool>;
timerGradient - shadow gradient at the top of the story below the timers <TimersGradient>;
panelSettings - displaying the bottom bar (should be enabled in the console) <PanelSettings>; (Details)
likeImage - images for the like button <UIImage>;
likeSelectedImage - images for the selected like button <UIImage>;
dislikeImage - images for the dislike button <UIImage>;
dislikeSelectedImage - images for the selected dislike button <UIImage>;
favoriteImage - images for favorites button <UIImage>;
favoriteSelectedImag - images for selected favorites button <UIImage>;
shareImage - images for sharing button <UIImage>;
shareSelectedImage - images for selected sharing button <UIImage>;
placeholderView - custom loader, should implement the protocol <PlaceholderProtocol>;
gamePlaceholderView - a custom game loader with progress, should implement the protocol <DownloadPlaceholderProtocol>;
closeReaderImage - image for reader's close button <UIImage>. Recommended 24pt;
closeButtonPosition - the position of the close button relative to the timers <ClosePosition>;
scrollStyle - animation style for slide transitions <ScrollStyle>;
presentationStyle - reader display style <PresentationStyle>;

StoryView

The main class for working with lists of stories.

Initialization

Remark
If the settings parameter was not specified for InAppStory, before initializing StoryView, it should be set:

InAppStory.shared.settings = Settings(userID: <String>, tags: <Array<String>?>)

To use the multi-feed function, feed: <String> must be set. By default, this is an empty string, and the list loads the main feed from the console. If the parameter favorite: <Bool?> is equal true, the list will be displayed favorite stories.

var storyView: StoryView!
    
override func viewDidLoad() {
	super.viewDidLoad()
	
   	storyView = StoryView(frame: <CGRect> = .zero, feed: <String> = "", favorite: <Bool> = false)
	storyView.target = <UIViewController>
        
	view.addSubview(storyView)
        
	storyView.create()
}

StoryUGCView

The main class for working with lists of UGC stories.

Initialization

Remark
If the settings parameter was not specified for InAppStory, before initializing StoryUGCView, it should be set:

InAppStory.shared.settings = Settings(userID: <String>, tags: <Array<String>?>)

To filter stories by attributes, you must pass the filter: Dictionary<String, Any> parameter when initializing the list instance. If you pass an empty filter, all stories from moderation section that passed approval will be displayed.

var storyView: StoryUGCView!
    
override func viewDidLoad() {
	super.viewDidLoad()
	
   	storyView = StoryUGCView(frame: <CGRect> = .zero, filter: Dictionary<String, Any> = [:])
	storyView.target = <UIViewController>
        
	view.addSubview(storyView)
        
	storyView.create()
}

Methods

create - running internal StoryUGCView logic;
refresh - refresh stories list;
present(controller presentingViewController: <UIViewController>, with transitionStyle: <UIModalTransitionStyle>) - displaying a custom controller on top of the story reader.

Parameters and properties

storiesDelegate - should implement the protocol <InAppStoryDelegate>;
deleagateFlowLayout - deprecated, renamed to delegateFlowLayout;
delegateFlowLayout - should implement the protocol <StoryViewDelegateFlowLayout>;
isEditorEnabled - displaying editor cell in sories lists; (InAppStoryUGC)
target - controller for reader display <UIViewController>;
direction - list scrolling direction. The default value for the list is horizontal(rows: 1), for favorites, the default value vertical(colums: 3). <ListDirection>;
isContent - there is any content in the list of stories <Bool>;
storyCell - custom cell, should implement the protocol <StoryCellProtocol!>;
editorCell - custom editor cell, should implement the protocol <EditorCellProtocol!>;

OnboardingStory

Onboarding is used to display stories not present in the main list.

Presentation

Remark
If the settings parameter was not specified for InAppStory, before showing onboarding, it should be set:

InAppStory.shared.settings = Settings(userID: <String>, tags: <Array<String>?>)

To display onboarding, you need call the showOnboardings method of the singleton class InAppStory.shared:

InAppStory.shared.showOnboardings(feed: <String> = "", limit: Int = 0, from target: <UIViewController>, with tags: [String]? = nil, delegate: <InAppStoryDelegate>, with panelSettings: PanelSettings? = nil, complete: <()->Void>)

Also, in the onboarding, you can show a separate list specified in the console. To do this, you must specify the feed: <String> parameter related to the feed. By default, this is an empty string, and the list loads the oboarding feed from the console.

limit: Int - limit for displaying the number of onboardings in one query. With limit=0 all available and unread at the moment are displayed.

tags: [String]? - override InAppStory settings tags;

Parametr panelSettings displaying the bottom bar (overwrite InAppStory.shared.panelSettings) <PanelSettings>; (Details)

To close the reader of onboarding, call closeReader(complete: () -> Void). This may be necessary, such as when handling open the link by push a button in story. complete called after closing the reader.

SingleStory

Used to display stories by their id or slug.

Presentation

Remark
If the settings parameter was not specified for InAppStory, before showing single story, it should be set:

InAppStory.shared.settings = Settings(userID: <String>, tags: <Array<String>?>)

To display single story, you need call the showSingle method of the singleton class InAppStory.shared:

InAppStory.shared.showSingle(from target: <UIViewController>, with id: <String>, delegate: <InAppStoryDelegate>, with panelSettings: PanelSettings? = nil, complete: <()->Void>)

Parametr panelSettings displaying the bottom bar (overwrite InAppStory.shared.panelSettings) <PanelSettings>; (Details)

To close the reader of single story, call closeReader(complete: () -> Void). This may be necessary, such as when handling open the link by push a button in story. complete called after closing the reader.

Protocols

InAppStoryDelegate

storiesDidUpdated(isContent: <Bool>, from storyType: <StoriesType>, storyView: <StoryView>?) - called after the contents are updated for sories type <StoriesType>;
storyReader(actionWith target: <String>, for type: <ActionType>, from storyType: <StoriesType>, storyView: <StoryView>?) - called after a link is received from stories with the interaction type <ActionType> and <StoriesType>;
storyReaderWillShow(with storyType: <StoriesType>, storyView: <StoryView>?) - called before the reader will show (optional);
storyReaderDidClose(with storyType: <StoriesType>, storyView: <StoryView>?) - called after closing the story reader (optional);
favoriteCellDidSelect() - called when the favorite cell has been selected (optional);
getGoodsObject(with skus: <Array<String>>, complete: <GoodsComplete>) - get goods items from parent app with closure, <GoodsComplete>;
goodItemSelected(_ item: <Any>, with storyType: <StoriesType>, storyView: <StoryView>?) - selected goods item in widget, with object sended in getGoodsObject(...)

GoodsDelegateFlowLayout

Methods of delegate, like in UICollectionViewDelegateFlowLayout

sizeForItemAt() -> <CGSize> - returns the cell size for the list;
insetForSection() -> <UIEdgeInsets> - returns padding from the edges of the list for cells;
minimumLineSpacingForSection() -> <CGFloat> - the spacing between successive rows or columns of a section;

StoryViewDelegateFlowLayout

Methods of delegate, like in UICollectionViewDelegateFlowLayout

sizeForItemAt() -> <CGSize> - returns the cell size for the list;
insetForSection() -> <UIEdgeInsets> - returns padding from the edges of the list for cells;
minimumLineSpacingForSection() -> <CGFloat> - the spacing between successive rows or columns of a section;
minimumInteritemSpacingForSection() -> <CGFloat> - the spacing between successive items of a single row or column;

PlaceholderProtocol

isAnimate: <Bool> { get } - returns the state of the animation
start - start animation
stop - stop animation

DownloadPlaceholderProtocol

func setProgress(progress: Double) - setting the progress value (0.0 - 1.0)

StoryCellProtocol

reuseIdentifier: <String> { get } - returns cell reuse identifier;
nib: <UINib?> { get } - returns the nib of the cell's visual representation;
storyID: <String!> { get set } - cell's story id;
setTitle(_ text: <String>) - story title;
setImageURL(_ url: <URL>) - image url for cover;
setVideoURL(_ url: <URL>) - video url for animated cover;
setOpened(_ value: <Bool>) - set new state if story is opened;
setHighlight(_ value: <Bool>) - set new state if story cell if highlighted;
setBackgroundColor(_ color: <UIColor>) - background color of cell;
setTitleColor(_ color: <UIColor>) - title color of cell;
setSound(_ value: Bool) - does the story have sound;

GoodsCellProtocol

reuseIdentifier: <String> { get } - returns cell reuse identifier;
nib: <UINib?> { get } - returns the nib of the cell's visual representation;
setGoodObject(_ object: <Any>!) - object that comes from getGoodsObject(...);

FavoriteCellProtocol

reuseIdentifier: <String> { get } - returns cell reuse identifier;
nib: <UINib?> { get } - returns the nib of the cell's visual representation;
favoritesCount: Int { get set } - total count of stories in favorites;
setHighlight(_ value: <Bool>) - set new state if story cell if highlighted;
setImages(_ urls: <Array<URL?>>) - a list of addresses of the first four images stories in favorites;
setImagesColors(_ colors: <Array<UIColor?>>) - a list of background colors of the first four stories in favorites;
setBackgroundColor(_ color: <UIColor>) - main background color of a cell;

###EditorCellProtocol

reuseIdentifier: <String> { get } - returns cell reuse identifier;
nib: <UINib?> { get } - returns the nib of the cell's visual representation;

Closure

GoodsComplete

Closure for contine getGoodsObject(...) method in InAppStoryDelegate - (Result<Array<Any>, GoodsFailure>) -> Void

enum

ListDirection

Direction of scrolling stories list, individual for each list

horizontal(rows: Int) - horizontal scrolling with the number of lines, the default is 1;
vertical(colums: Int) - vertical scrolling with the number of columns, the default is 3;

ScrollStyle

Story transition animation style in reader:

.flat - usual, one after another, like UIScrollView;
.cover - covered with next slide;
.depth - covered with next slide with previos slide alpha;
.cube - in the form of a 3D cube;

PresentationStyle

Reader display animation style:

.crossDissolve - showing reader from transparency;
.modal - modal reader display;
.zoom - display reader from list's cell;

ClosePosition

Position of the close button on the card in the reader:

.left - to the left of the timers;
.right - to the right of the timers;
.bottomLeft - on the left under the timers;
.bottomRight - on the right under the timers;

ActionType

The action by which the link was obtained:

.button - push the button;
.swipe - swipe up slide;
.game - link from Game;
.deeplink - deeplink from cell.

StoriesType

The action by which the link was obtained:

.list(feed: <String>?) - type for StoryView, feed - id stories list;
.single - type for single story reader;
.onboarding(feed: <String>) - type for onboarding story reader, feed - id stories list.

Quality

Quality of cover images in cells

.medium;
.high.

GoodsFailure

Failure that return in Result from getGoodsObject(...) closure

.refresh - show refresh button in the GoodsView;
.close - close GoodsView.

Objects

Settings

Parameters

userID - unique user identifier <String>;
tags - list of tags for content filtering <Array<String>>;

PanelSettings

Parameters

like - displaying the bottom bar with likes (should be enabled in the console) <Bool>;
favorites - displaying the bottom bar with favorites (should be enabled in the console) <Bool>;
share - displaying the bottom panel with sharing (should be enabled in the console) <Bool>;

TimersGradient

Parameters

colors - array of gradient colors <Array>;
startPoint - start point of gradient <CGPoint>;
endPoint - end point of gradient <CGPoint>;
locations - smooth gradient location <Array>;
height - the height of the gradient from the top edge of the story <Double>;

WidgetStory

Parameters

id - unique identifier of story <String>;
title - story title <String>;
image - link to cover image <String>;
color - background color of the story in HEX format <String>;

CustomGoodsView

To create your own goods widget, you need to inherit from CustomGoodsView.

setSKUItems(_ items: Array<String>) - set SKUs of goods from InAppStory reader;
setReaderFrame(_ frame: CGRect) - set StoryReader frame;
final close() - needs call from superclass, for close widget;
final goodsItemClick(with sku: <String>) - send statistic in SDK;

EditorCellSettings

To change the appearance of the UGC editor cell, use this object.

Parameters

backgroundColor - background color of the cell <UIColor>
iconColor - tint color of the icon in the cell <UIColor>
iconImage - custom icon <UIImage>

NotificationCenter

Events

Standard fields userInfo: id, title, tags, slidesCount, feed. The exception is StoriesLoaded

StoriesLoaded - the list of stories has loaded, StoryView is ready to work (fires every time the list is loaded, and also on refresh). In userInfo only field count - stories count & feed - stories feed id;
ClickOnStory - click on story in the list with additional parameters:
- place where the click came from (list or favorite);
ShowStory - display of the story reader with additional parameters:
- source - place where the showing came from (direct, onboarding, list or favorite);
- action - how the stories was shown (open, auto, list, swipe, tap or custom);
CloseStory - closing story with additional parameters:
- index - index of the slide from which the closure occurred,
- action - closing action (swipe, click, auto or custom),
- source - place where the closing came from (direct, onboarding, list or favorite);
ClickOnButton - click on the button in the story with additional parameters:
- index - index of the slide from which the get link,
- link - string link;
ShowSlide - show slide with additional parameters:
- index - index of the slide that now show;
- payload - innformation from console parametrs;
LikeStory - story like with additional parameters:
- index - index of the slide which "like" pressed,
- value - value of "like" position (true - is like, false - isn't like);
DislikeStory - story dislike with additional parameters:
- index - index of the slide which "dislike" pressed,
- value - value of "dislike" position (true - is dislike, false - isn't dislike);
FavoriteStory - adding story to favorites with additional parameters:
- index - index of the slide which "favorite" pressed,
- value - value of "favorite" position (true - is favorite, false - isn't favorite);
ClickOnShareStory - pushing the share button with additional parameters:
- index - index of the slide which "share" pressed;
StartGame - opening the reader with the game with additional parameters:
- index - index of the slide which game start;
CloseGame - closing the reader with the game with additional parameters:
- index - index of the slide which game closed;
FinishGame - closing the game at the end with additional parameters:
- index - index of the slide which game finished,
- result<Dictionary<String, Any>?> - game end results;
StoryWidgetEvent - action in widget with parameters:
- index - the index of the slide where the widget is located,
- widgetName - name of widget,
- data<Dictionary<String, Any>?> - activated widget data detail data fields;

Errors

In error notifications, userInfo also comes in the form of a dictionary ["errorMessage": <Error_message_string>]

SessionFailure - session error;
Reasons:
- session opening error;
- authorization key was not specified correctly;
- access is blocked;
StoryFailure - error in story;
Reasons:
- error loading stories list (onboarding/single/tape);
- problems with decoding data from the server;
CurrentStoryFailure - error when loading full story information;
Reasons:
- getting data for a specific story;
- setting/deleting likes, favorites, sharings;
NetworkFailure - network error;
Reasons:
- no internet connection;
RequestFailure - аn error occurred when requesting the server;
- statusCode - the server returned a statuscode;

tutu-ru-mobile/inappstory-ios-sdk

InAppStory

Contents

Installation

CocoaPods

Carthage

Swift Package Manager

Manual installation

Library import

Objective-C

Swift

Migration

InAppStory

Initialization

Methods

Parameters and properties

Customization

List

Goods widget

Reader

StoryView

Initialization

StoryUGCView

Initialization

Methods

Parameters and properties

OnboardingStory

Presentation

SingleStory

Presentation

Protocols

InAppStoryDelegate

GoodsDelegateFlowLayout

StoryViewDelegateFlowLayout

PlaceholderProtocol

DownloadPlaceholderProtocol

StoryCellProtocol

GoodsCellProtocol

FavoriteCellProtocol

Closure

GoodsComplete

enum

ListDirection

ScrollStyle

PresentationStyle

ClosePosition

ActionType

StoriesType

Quality

GoodsFailure

Objects

Settings

Parameters

PanelSettings

Parameters

TimersGradient

Parameters

WidgetStory

Parameters

CustomGoodsView

EditorCellSettings

Parameters

NotificationCenter

Events

Errors