Custom Invitation

Clients may use the SDK to create entirely custom invitations that not only control appearance, but also handle user interaction.

🚧

Custom invitations provide complete control over the invitation's appearance but are more complicated to implement. The default invitation is adequate for most applications.

Creating a Custom Invitation

You must (at a minimum) complete the following steps to show a custom invitation:

  1. Create a custom invite handler that conforms to the FSInviteHandler protocol. This protocol declares methods that are called when the SDK wants to show an invitation, close an invitation, or when there is an error.

  2. Register the invite handler with the SDK using:

[ForeSeeCxMeasure setInviteHandler:myCustomInviteHandler];
  1. Notify the SDK when an invitation has been accepted or declined using the following methods:

    • [ForeSeeCxMeasure customInviteAccepted];
    • [ForeSeeCxMeasure customInviteDeclined];

The SDK tracks everything necessary to determine a user's eligibility. If a user passes the eligibility criteria you've previously defined, is in the sampling pool, and a custom invite handler has been registered, then the SDK calls the following method on that invite handler:

- (void)showAndOnCompletion:(void(^)())completion;

Your implementation of this method should handle the presentation of your custom views. You must also notify the SDK when the user has accepted or declined your invitation.

If the user accepts your invitation, then call:

[ForeSeeCxMeasure customInviteAccepted];

If the user declines your invitation, then call:

[ForeSeeCxMeasure customInviteDeclined];

The SDK determines when it's safe to dismiss your custom invitation and call the following method once all processing is complete:

- (void)hideWithAnimation:(BOOL)animate completion:(void (^)())completion;

Your implementation of this method should handle hiding your custom invitation.

The SDK's public protocols are fully documented in the API documents.

Custom CONTACT Invitations

Custom invitations that use the CONTACT invite mode have additional requirements. Namely, you must provide the SDK with the user's contact details. The default invitation presents a text box to the user and asks them to manually enter this information. For custom invitations, however, you must provide the user's contact information using one of the following methods:

[ForeSeeCxMeasure setContactDetails:@"[email protected]" forType:kFSEmail];

Or:

[ForeSeeCxMeasure setContactDetails:@"555-555-5555" forType:kFSPhoneNumber];

In addition, you must set a preferred type, which tells the SDK which type of contact details you want to send for your users. For example:

[ForeSeeCxMeasure setPreferredContactType:kFSEmail];

If the SDK has an invalid input at the time that a custom CONTACT invitation is accepted, then the following delegate method is called:

- (void)setInvalidInput:(BOOL)isInvalid;

It is up to the custom invite handler to decide how to manage this error (e.g., ask the user to correct the information or treat it as a failure).

🚧

This method is at present only called when the given input is invalid (i.e., isInvalid is never NO). This may change in a future release, so checking the value is still recommended.

The SDK's public protocols are fully documented in the API articles.