Voucher Basics

The main concept of the SDK is a Voucher - a package containing the payment info, personalizations and an optional challenge.

During the Create process, the Voucher is in its Pending state - otherwise known as a PendingVoucher internally in the SDK. This pending state means that the Voucher can be modified and manipulated, but not sent.

Once the Voucher is ready to be sent, the pending state is removed and the Voucher becomes read-only. Any Voucher in the Claim process will be read-only and unmodifiable by the client.

Engine

The engine is the backbone of the SDK - it contains configurations used to style and control the appearance of the SDK (CommonConfig to handle SDK-wide parameters, CreateConfig and ClaimConfig to style their respective flows, and DiscoverConfig to handle the look of the Discover Screen) and managers to handle interactions with outside sources. These will be discussed in more detail in later sections.

Setting up the Engine follows a builder pattern - the main object is instantiated and is then followed by a chain of methods specifying different facets of the Engine. This chain is finished with the build() method which then applies the specified parameters to the Engine. This “Builder” pattern is carried throughout the app, and is also used in all the individual configs housed within the Engine.

Engine.Builder builder = Engine.Builder(localAuthInfo.serverUrl, localAuthInfo.sdkId)
        .setDebug(true)
        .addAnalyticsManagers(GoogleAnalyticsImp())
        .setGoogleImageSearchValues(GOOGLE_IMAGE_SEARCH_ID, GOOGLE_IMAGE_SEARCH_API)
        .setYouTubeVideoSearchApiKey(YOUTUBE_SEARCH_API)
        .setGiphyApiKey(GIPHY_API_KEY)
        .addAuthManager(emailAuthManager);

Engine engine = builder.build();

if(engine != null) {
    engine.startup(getContext());
}

val builder = Engine.Builder(localAuthInfo.serverUrl, localAuthInfo.sdkId)
                    .setDebug(true)
                    .addAnalyticsManagers(GoogleAnalyticsImp())
                    .setGoogleImageSearchValues(GOOGLE_IMAGE_SEARCH_ID, GOOGLE_IMAGE_SEARCH_API)
                    .setYouTubeVideoSearchApiKey(YOUTUBE_SEARCH_API)
                    .setGiphyApiKey(GIPHY_API_KEY)
                    .addAuthManager(emailAuthManager)

var build: Engine? = null
build = builder.build()
build?.startup(application)

The example above outlines a very basic implementation of the SDK Engine, and also includes the startup() call to handle the final necessary setup steps. Once the call to startup() has been made the Engine is active and is now ready to be used.

Configurations

Configurations provide finer control over individual parts of the SDK. Each of the main phases of the Voucher lifestyle has its own Configuration (Create, Common, Claim) as well as an additional Configuration to handle the look and behaviour of the Discover Screen.

ClaimConfig, CommonConfig, and DiscoverConfig are classes that can be found within the VouchrCommon package. These Configurations follow the same builder pattern as the Engine except they do not require an explicit startup() call to become active. Examples of all three can be found below.

Common Config

CommonConfig commonConfig = new CommonConfig.Builder().appName("Surpriise").giftVerb("Surpriise").build();

val commonConfig = CommonConfig.Builder().appName("Surpriise").giftVerb("Surpriise").build()

Claim Config

ClaimConfig claimConfig = new ClaimConfig.Builder()
                .setSupportedNoteTypefaces(new HashSet(Arrays.asList(getNoteTypefaces())))
                .setImageOptions(Arrays.asList(ClaimConfig.ImageOptions.CAMERA, 
                                                ClaimConfig.ImageOptions.GIPHY, 
                                                ClaimConfig.ImageOptions.GOOGLE,
                                                ClaimConfig.ImageOptions.GALLERY))
                .build();

val claimConfig = ClaimConfig.Builder()
        .setSupportedNoteTypefaces(HashSet(Arrays.asList(*getNoteTypefaces())))
        .setImageOptions(Arrays.asList(ClaimConfig.ImageOptions.CAMERA, 
                                        ClaimConfig.ImageOptions.GIPHY, 
                                        ClaimConfig.ImageOptions.GOOGLE, 
                                        ClaimConfig.ImageOptions.GALLERY))
        .build()

Discover Config

DiscoverConfig.Builder discoverConfigBuilder =
                DiscoverConfig.Builder.init()
                        .templateVersion(DiscoverVersion.V2)
                        .templateCornerRadiusDp(4f)
                        .templatePaddingDp(24)
                        .templateElevationDp(8f)
                        .templateGridColumnCount(1)
                        .templateShowActionButton(false)
                        .templateAspectRatio(1.6f);

    var discoverConfigBuilder: DiscoverConfig.Builder =
            DiscoverConfig.Builder.init()
                    .templateVersion(DiscoverVersion.V2)
                    .templateCornerRadiusDp(4f)
                    .templatePaddingDp(24)
                    .templateElevationDp(8f)
                    .templateGridColumnCount(1)
                    .templateShowActionButton(false)
                    .templateAspectRatio(1.6f)

All configurations have defaults that will be deferred to in the case that no preference is specified with one of the builder methods.

Create Configuration

In order to provide flexibility within our SDK, the Create Configuration behaves a little differently. CreateConfig is an interface that is located within the VouchrCommon package, which is then natively implemented in CreateConfiguration - located in the VoucherCreate package. This split was mainly done for package size reasons, but the functionality remains the same. Configurations should be handled by CreateConfiguration as opposed to CreateConfig. An example is shown below.

CreateConfiguration createConfiguration = new CreateConfiguration.Builder(context)
                .setCreateFlowController(getCreateFlowController())
                .setGiftItems(
                        new TipPersonalizationOption(this),
                        new TitlePersonalizationOption(),
                        new ToPersonalizationOption(),
                        new NotePersonalizationOption()
                                .setColorOptions(Color.BLACK, getResources().getColor(R.color.red),
                                                 getResources().getColor(R.color.surpriise_purple))
                                .setFontOptions(getNoteTypefaces()),
                        new WrappingPaperPersonalizationOption(),
                        new GifPersonalizationOption(),
                        new ImagePersonalizationOption(),
                        new GiftCardPersonalizationOption(),
                        new VideoPersonalizationOption(),
                        new AudioPersonalizationOption(),
                        new GamePersonalizationOption())
                .showSurpriiseFriends(true)
                .setCarouselEmptiedText(getString(R.string.your_surpriise_looks_awesome), 
                                                getString(R.string.tap_next_to_continue))
                .setRecipientRequired(true)
                .setMinimumGiftItemCount(1)
                .build();

val createConfiguration = CreateConfiguration.Builder(context)
        .setCreateFlowController(getCreateFlowController())
        .setGiftItems(
                TipPersonalizationOption(this),
                TitlePersonalizationOption(),
                ToPersonalizationOption(),
                NotePersonalizationOption()
                        .setColorOptions(Color.BLACK, getResources().getColor(R.color.red),
                                         getResources().getColor(R.color.surpriise_purple))
                        .setFontOptions(*getNoteTypefaces()),
                WrappingPaperPersonalizationOption(),
                GifPersonalizationOption(),
                ImagePersonalizationOption(),
                GiftCardPersonalizationOption(),
                VideoPersonalizationOption(),
                AudioPersonalizationOption(),
                GamePersonalizationOption())
        .showSurpriiseFriends(true)
        .setCarouselEmptiedText(getString(R.string.your_surpriise_looks_awesome), 
                                    getString(R.string.tap_next_to_continue))
        .setRecipientRequired(true)
        .setMinimumGiftItemCount(1)
        .build()

Accessing Data

Raw data pertaining to the current configuration can be accessed through the collection of Vouchr Manager Interfaces. These interfaces provide access to many features that are set either through the Configs discussed above or on the Vouchr Web Dashboard. Three main interfaces are provided to clients :

  • ContentManager - used to gain information about preconfigured media search terms, sound and gift package categories, available challenges and merchant information.
VoucherSDK.contentManager().getDefaultGiftPackage();

VoucherSDK.contentManager().getDefaultGiftPackage()
  • UserManager - used to request and update information about a particular user if the userId is known, as well as allow the current user to log into and log out of the SDK.
VoucherSDK.userManager().isLoggedIn();

VoucherSDK.userManager().isLoggedIn()
  • GiftManager - user to perform lifecycle actions on the current Voucher (wrap/unwrap, retrieve/create/activate/claim) as well as retrieve lists of created and received vouchers. Includes support for location based claiming as well.
VoucherSDK.giftManager().createVoucher();

VoucherSDK.giftManager().createVoucher()