Deeplinks for Stories

This guide shows you how to handle deep links in your application and show a story.

The Storyly Dashboard generates a deep link with the application's predefined custom scheme. The application needs to handle the setup of intent handling and route the related URI to Storyly SDK to open the related story.

Open Story

The first way to open the related story is to use the URI which is received from the dashboard:

self.storylyView.openStory(payload:URL)

[self.storylyView openStoryWithPayload:NSURL];

The second way to open a story is to use story group id, story id and play mode as in the function signature:

self.storylyView.openStory(storyGroupId:String, 
                           storyId:String?, 
                           play:PlayMode)

[self.storylyView openStoryWithId:NSString
                          storyId:NSString
                          play:PlayMode];

Play Modes

Playing to the End

If the PlayMode parameter is not defined or passed as Default , Storyly opens the Story Group and a specific Story (if storyId is provided) and all active Story Groups will be shown to the user. This is the default behavior.

Playing a Single Story Group

This mode plays only the specific Story Group. If the PlayMode parameter is defined as sg/StoryGroup, Storyly opens the Story Group and a specific Story (if storyId is provided) and shows only that Story Group whose storyGroupId is sent to the Storyly SDK.

Playing a Single Story

This mode plays only the specific Story. If the PlayMode parameter is defined as s/Story, Storyly opens the Story Group and the specific Story (storyId is required) and shows only that Story whose storyId is sent to the Storyly SDK.

StorylyStoryPresentFailed Event

This event will let you know that Storyly could not open Story programmatically and had a problem about parameters (Story Groupd ID, Story ID or Play Mode). In this case, users will still able to see story group icons with data. In order to get notification about this event, you should override the following function in StorylyDelegate, which you have registered in Initial SDK Setup.

In order to notified about this event, use the following example:

func storylyStoryPresentFailed?(_ storylyView: Storyly.StorylyView,
                                errorMessage: String) {}

- (void)storylyStoryPresentFailed?:(StorylyView *)storylyView
                      errorMessage:(NSString *)errorMessage {}

🚧

Warning

Application can determine from URL's host if it's related with Storyly, host will be storyly for Storyly Dashboard generated deep link URLs.

🚧

Warning

You need to set the URL Scheme for Deep Links field in the Storyly Dashboard -> Settings -> App Settings in order to get the deep links properly from the dashboard.

🚧

Warning

Make sure that the application schema is defined in your application's Info.plist file.

Instagram Share Config

This class shows the configuration information of Storyly > Instagram Share.

Set Facebook App ID

This function allows you to set your Facebook app ID, since it's required to share on Instagram.

storylyView.storylyInit = StorylyInit(
            storylyId: STORYLY_INSTANCE_TOKEN,
            config: StorylyConfig.Builder()
               .setShareConfig(
                    StorylyShareConfig.Builder()
                        .setFacebookAppID(id: String)
                        .build()
                )       
                .build()
        )

Brand Domain Config

This guide shows you how to use your own domain while sharing deeplinks for stories.

📘

Before you begin

You need to handle deeplinks in your application as described in Deeplinks for Stories.

Normally, when you get the deeplinks from Storyly Dashboard -> Settings -> App Settings, they are in this format: https://open.storyly.io/share/v2/{story_id}.

With following methods, you can use your own domain while sharing a deeplink in this format: https://example.com?id={story_id}.

Here are two methods to handle this on your backend:

package main

import (
	"fmt"
	"log"
	"net/http"
	"net/http/httputil"
	"net/url"
)

func ReProxy(remote *url.URL, p *httputil.ReverseProxy) func(http.ResponseWriter, *http.Request) {
	return func(w http.ResponseWriter, r *http.Request) {
		storyID := r.URL.Query().Get("id")

		if storyID == "" {
			http.NotFound(w, r)
		} else {
			r.Host = remote.Host
			r.URL.Path = fmt.Sprintf("/share/v2/%s", storyID)
			p.ServeHTTP(w, r)
		}
	}
}

func main() {
	remote, err := url.Parse("https://open.storyly.io")
	if err != nil {
		panic(err)
	}

	proxy := httputil.NewSingleHostReverseProxy(remote)

	http.HandleFunc("/", ReProxy(remote, proxy))

	if err := http.ListenAndServe(":9090", nil); err != nil {
		log.Fatal("ListenAndServe: ", err)
	}
}

package main

import (
	"fmt"
	"log"
	"net/http"
)

func Redirect(w http.ResponseWriter, r *http.Request) {
	storyID := r.URL.Query().Get("id")

	if storyID == "" {
		http.NotFound(w, r)
	} else {
		redirectionURL := fmt.Sprintf("https://open.storyly.io/share/v2/%s", storyID)
		http.Redirect(w, r, redirectionURL, 302)
	}
}

func main() {
	http.HandleFunc("/", Redirect)

	if err := http.ListenAndServe(":9090", nil); err != nil {
		log.Fatal("ListenAndServe: ", err)
	}
}

🚧

Warning

Make sure that your URL includes {story_id} as variable to indicate shared story, Storyly SDK will automatically replaces this. Moreover, do not forget the replace it in your backend with correct parameter as shown in samples.

After handling brand domain usage in your backend, you can use the following function in the initialization process:

self.storylyView.storylyInit = StorylyInit(
            storylyId: storylyToken,
            config: StorylyConfig.Builder()
                .setShareConfig(
                    StorylyShareConfig.Builder()
                        .setShareUrl(url: String)
                        .build()
                )
                .build()
        )