This documentation will help you with building your Rock Mobile application. Be sure to check back regularly for updates. You can browse this documentation using the sidebar on the left or by searching in the top right (use the keyboard shortcut Ctrl+K).

Let's begin by creating a new mobile application within Rock. Mobile applications can be found under Admin Tools > CMS Configuration.

Select the Mobile Applications box to view a list of all the apps in your Rock instance.

Click the Plus icon to create a new app, or select a previously created app from the list below.

This section refers to the 'CMS' mobile block group.

Now it's time to configure your app. There are some options that are not covered below; they are beyond the scope of this walkthrough. Start by filling in the Application Name and optional Description.

Application Type

You have three options when it comes to the Application Type. Choose what makes the most sense for your app; you can always change your selection later.

Blank (not recommended)

This option will not provide a Flyout panel or tabbed navigation. Generally you'll want one of those, so Blank should only be selected when you need to remove those elements for a specific use case.

Flyout (recommended)

This is the most common type of application and one your users will be familiar with. A menu icon (three horizonal bars) will be displayed in the top left of your app and when pressed will reveal a slide out panel form the left side. Users can also swipe from the left side of the screen to reveal the Flyout panel.

Tabbed

When this option is selected users will be shown a tabs at the bottom of the app. If your app only has a few top-level pages this can be a great alternative to the Flyout. Each page can have a custom image associated with it which is displayed above the name.

Lock Orientation

You can force the application to be locked in Portrait or Landscape mode for both phones and tablets. Generally you'll want to leave these set to the defaults of Portrait for the phone and empty for the tablet.

Application Pages

You'll have the option to set the Login, Profile, and Communication View pages here... but we haven't created them yet. Although this guide won't dig into setting these up, know that coming back to add these page links is important for the app to understand where these fundamental areas exist for navigation.

API Key

Bad: mobileapp, Rock, testing Better: Gr33nToolb0x, ctr2p7

Flyout XAML

If you've selected an Application Type of Flyout then you can customize what appears inside via XAML. The default template will include a <ListView> that references a {Binding MenuItems} source; this will automatically add any pages with the Display In Navigation option checked. It is recommended to leave this alone unless you need custom functionality.

Homepage Routing Logic

Rock Mobile uses blocks the same way as Rock Web does. You create pages, add blocks to them, and configure them. Then when you deploy your app all that information will get bundled up so the mobile app knows how to communicate with your site.

Many blocks are self-explanatory, though we're not saying they don't need some documentation too. We'll continue adding some helpful hints about all the blocks, such as what is available in Lava merges and what-not.

Integrated Scroll

In some cases, you may want a block to stretch to the full height of the zone (in 99% of cases, this entails the entire screen). In Xamarin, this was achieved by the use of a now-deprecated FillAndExpand property.

In MAUI, this is achieved through the use of an attached property. Within the block, you want to expand add a Rock:Zone.Expands="true" property on the outermost layout.

This block is useful for quickly displaying content channel items like messages or promotions. Instead of writing an entity command to get the data, this block will pull the full content channel item for you.

Parameters

Context can be provided to the block via item Id or Guid; you don't need to pass both.

Settings

Template

The Lava commands that are enabled for this block will only Lava rendered on the server.

Merge Fields

For example, you could use it to display a simple label:

Block Configuration

Dynamic Content This setting is extremely useful. When checked, it will download fresh content from the server every time the page is initialized. In a sense, it causes the content to "refresh" every time the page is loaded.

If you have static, unchanging content, you can leave this as a No. This means that a Deploy will be required before the content is updated in-app. Behind the scenes, this content will be baked into the shell bundle that's downloaded during the app launch. Lava will still be processed, but you won't have a CurrentPerson context.

Using Lava

After the content, the second block setting to discuss is the "Enabled Lava Commands". If you have a Lava command within your Content, it is important to make sure to check the applicable settings here. It is also just as vital to make sure that you check the "Process Lava on Server" setting within the 'Block Properties > Mobile Settings', as seen here:

Entity Context

Using the Context Entity Type setting in the block, you can select any of the available entities.

Next, you'll need to set the context parameter for the page. This is how the block will know where to find the context identifier. This setting is found by editing the Page (not the block) and expanding the Advanced Settings section. Based on the entity type you chose, you should see a setting labeled {{ Entity }} Parameter Name. Add a parameter key that makes sense for your data.

Now that you've set the block entity type and page context parameter, be sure to Save and Deploy. The final step is to simply link to your page and pass the appropriate context via the key you set. Going back to the example of the person profile page, you might end up with something like this:

Block Configuration

Page Size

The number of items to send per page.

Detail Page

The page to redirect to when selecting an item.

List Template

The Lava used to generate the JSON object structure for the item list.

List Data Template

The XAML for the lists data template.

Merge Fields

In the template, you have access to these objects:

Want big, styled images that you can overlay with Lava content? You're in the right place. Hero images are a great way to attractively display a picture with text overlay.

Example

This is an example of a display created using this block. The Background Image was set to a stock photo, and to render the title, the block setting was set to {{ CurrentPerson.FirstName }}.

Using Lava

Block Settings

Title

The main title that overlays the Background Image. Lava enabled.

Subtitle

The text that overlays the image, underneath the title. Lava enabled.

Background Image

Phone: The image to display on a phone. Recommended to be at least 1024px wide, and at least double the height of the Height - Phone setting.

Tablet: The image to display on a tablet. Recommended to be at least 2048 pixels wide, and at least double the height of the Height - Tablet setting.

Height

Phone: The height of the rendered image on a phone.

Tablet: The height of the rendered image on a tablet.

Text Align

This setting allows you to align the overlayed text to the left, center or right side of the image.

Title Color

Subtitle Color

Padding

The purpose of this block is pretty obvious, but in case you are unsure, it is to log a registered individual into your application using a Rock credential.

If you need to set up registration, check out the Register or Onboard Person blocks.

Login Page App Setting

When you create an instance of the Login block, it would be a good idea to also set the Login Page application setting. This allows the app to perform auto-security redirects and is used in a couple of other places functionally.

Settings

Page Parameters

The following page parameters are recognized by the Login block.

External Authentication

Listed below is the corresponding documentation for every external authentication provider that can be integrated with Rock Mobile.

If/when more are added, corresponding documentation will be added to this section.

This one is going to be a challenge to describe, but we'll get you up to speed on how to use it. This block allows you to build a visual interface to provide challenges to your people. These challenges span multiple days and comprise one or more individual challenge items on each day. An example might make more sense of what we are talking about.

Let's suppose you want to have a 7 day "Get to Know God" challenge. Each day they are prompted to complete two tasks: Prayer and Bible reading. Each day would give different instructions about what to pray for and what verses to read. When they first land on the page hosting this block they will see the challenge items for day 1. After they tick those off they might see a "way to go" type message. Then the next day when they return they will see the items for day 2, and so on. Once they finish day 7 and come back the next day they start on day 1 again.

Lava Reference

When your lava template is parsed, you will get a number of merge fields to help you render the daily challenge. There is some sequence of operations you will need to be aware of.

First, you will probably want to check if the CompletedChallenge merge field is not null. If it contains a value then that means the user just finished the final challenge item for a day. In this case, you likely want to display some kind of "well done" message, or possibly switch to a read-only view that removes the check-boxes - since trying to uncheck an item from a fully completed day is not allowed. In this case, the Challenge merge field may contain either the same object as the CompletedChallenge or it may contain what the system thinks is the "next" daily challenge, depending on the situation. But generally you probably don't want to just display whatever is in the Challenge at this point.

Secondly, if the MissedDates merge field contains any values then those should be displayed to the user and must be filled in before you display the challenge in the "Challenge" merge field. Otherwise, they will start a new challenge. Also, the MissedDates must be filled in sequentially. Meaning, if they missed two dates they need to fill in the challenge for the first date and then the second date, otherwise it will also break the challenge and start them over. The default template displays just the first date of the array.

Merge Fields

• MissedDates - An array of dates that indicate the user has missed one or more dates in their current challenge that they can still go back and fill in. Note that this merge field will be empty if you have requested by any means that a specific challenge be shown.

• TodaysChallengeGuid - The unique identifier of the daily challenge that indicates today's challenge. This can be different than the Challenge value in as it takes into account an ongoing challenge where they might have skipped some days. One exception to this is if you pass a query string parameter of DailyChallengeGuid to request a specific challenge then this value will match that challenge.

Object Structure

ChallengeState

• Guid - The unique identifier of the daily challenge.

• IsComplete - Will be true if the individual has completed the challenge corresponding with this day.

DailyChallenge

This object contains all the details about a single day of a challenge.

• Guid - The unique identifier of the daily challenge.

• HeaderContent - This contains the same text content as the "Content" box when editing the "Day 1", "Day 2", etc. items. This is normally displayed at the top of the page before any checkboxes.

• IsComplete - Will be true if the individual has completed this daily challenge already. For example, if they have just checked the last checkbox, or if you are linking directly to a previously completed daily challenge.

• AttributeValues - If you defined any custom attributes for the daily challenge then they will show up here. This is a dictionary of attribute keys and string values.

ChallengeItem

This object contains the information about a single checkbox item that will be displayed for the user to complete.

• Guid - The unique identifier of the challenge item.

• Title - The text from the content channel item title. This is normally displayed next to the checkbox.

• Content - The text from the "Content" box of the content channel item.

• AttributeValues - If you defined any custom attributes for the challenge item then they will show up here. This is a dictionary of attribute keys and string values. You can use this to provide custom rendering logic to your lava template. It will not include the "InputType" value.

ChallengeItemValue

Contains the user-supplied information about a single challenge item. Meaning, if it has been completed and any custom user value that was entered.

• Guid - The unique identifier of the challenge item this value is for.

• IsComplete - Will be true if the checkbox is checked.

• Value - Contains any custom value the user has typed into a text field for this item.

XAML Bindings

So your lava template will set up the initial XAML content to paint the page. But how do you link user actions (like tapping a checkbox) back so it actually does something? There are some special bindings available to you:

• Challenge.ToggleChallengeItem - A command that toggles a checkbox on or off. The command parameter is the item unique identifier.

Okay, so those are the XAML bindings available. But examples certainly make more sense than just the description. For a moment, lets imagine that all we are going to display is a checkbox and the name of the item to be completed. So we will loop through the Challenge.ChallengeItems array and render out a horizontal stacklayout to contain our checkbox and then the label.

{% for item in Challenge.ChallengeItems %}
    <StackLayout Orientation="Horizontal" Spacing="0">
        <Rock:Icon IconClass="{Binding Challenge.ItemValues[{{ forloop.index0 }}].IsComplete, Converter={Rock:BooleanValueConverter True=check-circle, False=circle}}"
            TextColor="{Binding Challenge.ItemValues[{{ forloop.index0 }}].IsComplete, Converter={Rock:BooleanValueConverter True=#EF8903, False=#C3CED1}}"
            Margin="0 8 0 0"
            VerticalOptions="Center"
            Command="{Binding Challenge.ToggleChallengeItem}"
            CommandParameter="{{ item.Guid }}" />
                    
        <Label Text="{{ item.Title | Escape }}"
            VerticalTextAlignment="Center"
            VerticalOptions="Center"
            StyleClass="challenge-title">
            <Label.GestureRecognizers>
                <TapGestureRecognizer Command="{Binding Challenge.ToggleChallengeItem}"
                    CommandParameter="{{ item.Guid }}" />
            </Label.GestureRecognizers>
        </Label>
    </StackLayout>
{% endfor %}

Most of that should look pretty normal to you. We have a bit of a mix between lava and bindings. In some places we are using lava to display a value (for example, the Label text). In others, you will notice we are using binding values. The binding value means it will actually persist the change in value. If we had used a normal lava "if" statement then it wouldn't automatically update or track the change in value.

But, that binding syntax is probably not what you normally see, so let's break it down. There are two parts to the binding, first is the path and then the converter. Let's take a look at that path first.

Challenge.ItemValues[{{ forloop.index0 }}].IsComplete

This is binding to the array Challenge.ItemValues and then binding to a specific item in the array, identifies by {{ forloop.index0 }}, which is the index of the item being processed in the loop. Finally, in that particular indexed object we are binding to the IsComplete property. Next is the converter.

{Rock:BooleanValueConverter True=check-circle, False=circle}

What we are doing here is taking that boolean value from the IsComplete property and running it through a converter that will return different values depending on if the value is true for false. If it is true we return check-circle and if it is false it returns circle. This gives us the allusion of a nice checkbox that we can style ourselves.

Setup

So how do you set up these challenges? You are going to use a Content Channel to do that. You will also need to setup 2 Content Channel Types (if you set up multiple challenges you can re-use these channel types).

Content Channels Types

The first content channel type will hold the challenges that you are going to set up, in this case we are talking about your 7-day "Get to Know God" challenge. To create a general use Content Channel Type for these challenges. Create a new Content Channel Type with the following settings:

• Name = Multi-Day Challenge

• Date Range Type = No Dates

• Disable Priority = Yes

• Disable Status = Yes

• Show in Channel List = Yes

Next, create a second Content Channel Type that will hold the individual items to be completed each day.

• Name = Challenge Items

• Date Range Type = No Dates

• Disable Priority = Yes

• Disable Status = Yes

• Show in Channel Lists = Yes

• Item Attributes

  • Name = Input Type

  • Field Type = Single-Select

  • Values = Text,Memo

  • Control Type = Drop Down List

The item attribute allows you to specify that the challenge item should have a (required) input field. You can also define other item attributes and these will be included in the Lava so you can better customize how things are displayed.

Content Channels

First, we are going to create the content channel that will hold the individual challenge items to be completed each day.

• Name = Challenge Items

• Type = Challenge Items

• Default Content Control = Code Editor

Now you need to create a Content Channel for the actual 7-day challenge.

• Name = Get to Know God

• Type = Multi-Day Challenge

• Child Content Channels = Challenge Items (the one you just created above)

• Items Manually Ordered = Yes

• Child Items Manually Ordered = Yes

Day Items

It may seem obvious, but you need to create a Content Channel Item inside your "Get to Know God" channel for each day. To keep things simple, just create 7 items titled "Day 1", "Day 2", and so on up to "Day 7". If you get things out of order, you can use manual sorting to put things in the proper order. That order is used to determine the order of the days, not the title.

All you really need is the Title, but you can enter some XAML in the Content that will be displayed at the top of the page when viewing that day's challenges.

Challenge Items

Go into "Day 1" and create a new child item.

• Title = Pray for 15 minutes

Then add a second item to be the challenge item for reading the bible.

• Title = Read the Bible

• Content = <Label Text="Genesis 1:1-18" />

So we now have two items that will be displayed for "Day 1". The first is a checkbox with the title "Pray for 15 minutes" and no additional content. The second item will be a checkbox with the title "Read the Bible" and then below that it will display the verses that they are supposed to read.

To complete this you would do the same for "Day 2" through "Day 7". And obviously you can use different verse references. You can even have them in different order or additional items to be completed on certain days.

This block is pretty self-explanatory. It can be used to edit the profile details of the currently logged-in individual.

Block Configuration

Connection Status

The connection status to use for new individuals. Defaults to Prospect.

Record Status

The record status to use for new individuals. Defaults to Pending.

Showing/Requiring Fields

In the Mobile Local Settings, each field follows a specific pattern. There is one setting for whether or not to show a field, and another that determines whether or not the field is required. If show is set to No, then the required field is irrelevant. This takes place for every field on that list, although the Gender field follows a newer style, the concept is the same (because it was added later).

Modifying Another Person Profile

In order to modify another person's profile, you must pass in the PersonGuid as a page parameter. Note that you must have access to make modifications.

What is Auth0?

Auth0 is a cloud-based identity and access management (IAM) platform that provides developers and organizations with secure and easy-to-use solutions for authenticating and authorizing user access to applications. Auth0 offers a range of authentication methods such as username and password, social identity providers, multi-factor authentication, and more.

With Auth0, developers can add authentication and authorization capabilities to their applications quickly and easily. Check out their website to learn more about the services they offer.

Setup

To ensure Auth0 works seamlessly in Rock Mobile, follow this step-by-step guide to configure a new Auth0 application for Rock Mobile. In this guide, we will:

1. Create and configure a new Auth0 application for Rock Mobile.

2. Configure Auth0 to provide enough data for Rock sign-up.

3. Configure Rock Mobile to support Auth0.

Creating an Auth0 Application

To begin, let's create the Auth0 application that will handle our Rock Mobile logins. You should only need one application for all of your mobile applications.

1. Select Native as the type of application.

2. Head into the Settings of the Application. You can ignore the Quick Start guide that they typically start you on. Note down the Client ID and Domain of your Auth0 application.

1. Make sure you have your app's Bundle ID (iOS) and Package Name (android) available. If you are unsure of these values or where to retrieve them you should contact the AppFactory publishing service.

2. In the Allowed Callback URLs of the Auth0 application, add an entry in the following format. If your package name and bundle identifier differ, you will require two URLs, one for each.

1. Under Credentials, ensure the Token Endpoint Authentication Method is set to None. Mobile apps use a different form of authentication in comparison to web applications.

Great! We should now have all of the basic configuration finished.

Getting Additional Data for Rock

In order to sign a person up, Rock requires a First Name, Last Name, and either a Phone Number or an Email. Auth0 does not require all of these data points out of the box. There are quite a few ways that you could customize the login flow to support this additional data, but we're going to keep it pretty straightforward in this guide.

To ensure all of the necessary data for Rock is obtained, we will:

1. Configure Universal Login to add additional fields for database sign-up.

2. (optional) Configure a post-login rule to pass additional information to Rock.

Configuring Universal Login

1. First, we need to configure Auth0's Universal Login to ensure there is enough data collected to create a person in Rock. Head over to Branding > Universal Login > Advanced Options > Login. Enable the Customize Login Page option.

The entire file looks like this if you want to copy and paste the entire example.

Once finished, paste it into the HTML section into the box. Ensure the preview looks correct.

(optional) Pass in Additional Information to your Rock instance

There are a billion ways in which you can configure your Auth0 login process. You may want to enhance the process to return additional information to your Rock instance (such as Gender, BirthDate, etc).

This will add a Gender picker that reflects the Gender enum, and a basic Phone Number field.

1. Jump into Action > Flows and press Login to configure a post-login flow. Select Build Custom.

1. In onExecutePostLogin method, configure the identity claims to pass down the proper data, like such:

Press Deploy. The last thing we need to do is add it to the login flow. Add the Action you just created before the completion of the login, like such. Make sure to press Apply afterwards.

Configuring Rock Mobile

There are a couple of configuration steps for Rock Mobile.

1. In your mobile application (Cms Configuration > Mobile Applications), look for the Auth0 Client ID and Auth0 Domain settings. Update them with your application values.
2. Enable Auth Login in the Login block.

   Hooray! You should now be fully capable of handling Auth0-related logins.

Go into your login block, and press the Login With Auth0 button. That button has a btn-auth0 style class applied for customization. You should now be prompted with an Auth0 login.

In the Sign Up tab, you should see all of the additional fields you configured.

When you successfully log in with Auth0 (even for new accounts), a Person in Rock will be matched or created with the values of the Auth0 account.

Supported Claims

The following identity claims are supported and can be utilized to supply additional information about a Rock Person. Since Auth0 configurations can vary, we supply a few different keys that are recognized and translated accordingly.

This section refers to the 'CMS' mobile block group.

This section refers to the 'Communication' mobile block group.

Page Parameters

Block Configuration

This block allows an individual to register for a new account. There are a number of options that control what information you collect and which bits are required.

Block Configuration

Person Matching

In order for person matching to work, there are a few things that must come together:

1. Block Settings

   1. Check For Duplicates (Enabled by default)

   2. Confirmation Page (You must configure this)

   3. Confirm Account Template (Configured by default)

2. Mobile Shell Version 3 or Later

3. E-mail Address Provided by Individual

The first is, obviously, that you must turn on Check For Duplicates. This is the primary setting that dictates if the entire feature is enabled or not.

Once that is enabled, you also need to specify the Confirmation Page that the user will be sent to from their e-mail. This is a web page and not a mobile page, for example on your External Website you would select the "Support Pages > Account Confirmation" page.

Third, you must select the system e-mail that will be used as the template when generating the e-mail. This is selected by default.

In addition to the above block settings, there are two other things. First, as is pretty clear from the above, your users must be using version 3 or later of the Mobile Shell. This is because additional support was added in the shell to handle the UI to inform the user that the account was created but they need to confirm it. If an individual is running version 2 or below of the Mobile Shell then they will get the old behavior, which is no person matching.

Finally, they must provide an e-mail address. Because we need to send an e-mail when performing person matching the user must enter an e-mail address. This causes strict matching to be enabled in the search which means only people whose current, or previous, e-mail matches the one being searched for are considered for the duplicate search. Since adding a new user login to an existing person is a security-sensitive process, we need to be more strict about these things.

This block displays structured content from Rock in the app. You can use this to display interactive sermon notes with tap-to-reveal areas and note-taking areas.

Block Settings

Content Channel

You'll see a channel called "Message Notes" that comes out of the box with Rock, so you typically won't need to set this up manually unless you have another purpose in mind. When editing a content channel, you can check the Is Structured Content option to enable this functionality. This will change the Default Content Control option to Editor Tool Configuration.

Mobile App

In the app, you'll need a page with the Structured Content View block added. Thankfully there aren't any block settings to worry about, so you'll just need to add a link to this page that passes context using the ItemGuid query string with a value of the content channel item GUID. In the case of Message Notes, you can use Lava to look at the ChildItems of a message to get the Notes/Structured Content item.

Supported Formatting

Not all formatting options are supported natively in the app, but here's what can be used safely:

1. Text

2. Heading

3. List (ordered and unordered)

4. Image

   1. Image captions

5. Checklist

6. Quote

   1. Left-aligned

   2. Center-aligned (stays aligned left)

7. Warning

8. Code

9. Note (can be left blank or default content entered)

10. Delimiter

11. Link

12. Table

When highlighting text, the following formatting is supported:

1. Bold (depending on font support)

2. Italic (depending on font support)

3. Link

4. Marker

5. Fill-in

6. Code

Notes

When using note blocks in structured content, they will only display if a user is logged in. We recommend putting a content block above this one that only displays if a user is not logged in, and prompts them to log in or at least lets them know that the notes are missing until they do so.

Overview

At first glance, check-in seems simple—just a way for someone to say, "I'm here!" However, from a technical perspective, recording this data involves several requirements. To streamline the process, we've broken down these requirements and provided solutions to ensure the check-in block is as seamless as possible.

Block Configuration

Check-in Settings

Check-in Configuration

This is a required setting. The configuration template to use for this check-in block.

Kiosk

This is a required setting. The kiosk to associate this check-in process with. Necessary for things like location based check-in, etc.

Primary Areas

The areas directly associated with the check-in configuration, to make available to this block.

Secondary Areas

The areas not directly associated with the check-in configuration.

Mobile Settings

Loading Screen Template

The XAML content to display when the block is loading data.

Completion Screen Template

The XAML content to display when a check-in process successfully completes.

Login Screen Template

The XAML content to display when a user presses log-in. If no content is provided, the application Login page will be used.

Allow Add Family Member

Whether or not you should be able to add a new family member during the check-in process.

Add Person Attributes

The custom attribute fields to display when a family member is being added.

Page Parameters

Data Requirements

Successful check-in requires a lot of data. The diagram below highlights the key information needed to have a complete check-in process:

If any required data is missing, the UI will prompt the user, potentially extending the check-in process. However, by providing more context through page parameters—such as using deep links, QR codes, or NFC tags—you can create a faster, more seamless experience.

Additionally, Rock intelligently fills in missing data where possible. For example, if only one applicable schedule exists for the selected Area, Group, and Location, that step is skipped automatically. This especially applies to schedule because you can't pass that one in through page parameters.

Providing Context

The more data you can give the check-in process, the better.

When navigating to the Check-in (through a deep link, or from anywhere) you can pass in the parameters like such:

The query string in this instance would tell the block which configuration to use, while expecting the block settings to fill in the remaining gaps.

Deep Linking

Let's say you wanted to provide an NFC token in the Bears Room that could be tapped to Check-In. Your deep link route would look something like:

Your NFC token would be encoded to something that looks like:

Assuming that the AreaId, LocationId and KioskId are all the proper values for that schedule, if there is only one available person to check-in, you would likely be navigated directly to the success screen. You have successfully filled in most of the needed information for checking-in without the end-user knowing a thing. Magic!

This section refers to the "Connection" mobile block group.

This guide will walk you through the process of creating a new mobile application in Rock: adding some content, deploying, and finally testing with the Rock Mobile Core app. When we're finished you'll have everything you need to begin building the app of your dreams.

Block Configuration

Communication List Categories

Select the categories of the communication lists to display, or select none to show all that the user is authorized to view.

Show Description

If enabled then the description of the communication list will be shown.

Show Medium Preference

If enabled, a segment picker will be displayed for lists that the person is subscribed to in order to set their preferred communication type.

Show Push Notification as Medium Preference

If enabled, push notification will be displayed as an option for medium preference.

Filter Groups By Campus Context

If enabled, groups will be filtered by the current campus context. If a campus is not set on the communication list, then it will be displayed no matter what.

Always Include Subscribed Lists

When filtering by campus, you may want to display lists that the user is subscribed to regardless of the campus context. Enabling this will do just that.

Styling

Configuration

Snippet Type

The type of snippets that will be made available via the snippet keyboard button.

Message Count

The number of messages to be returned each time more messages are requested.

Database Timeout

The number of seconds to wait before reporting a database timeout.

Page Parameters

The following query string parameters are recognized and utilized by this block.

Styling

Message Bubbles

To style message bubbles, we introduced the following custom CSS classes.

You can target these elements by using the ^MessageBubble selector.

^MessageBubble {
  -rock-inbound-background-color: orange;
}

This block is simple to use, but it's important to understand its function. When authoring a new push communication, you may have seen the question for Open Action, which includes the options Link to Mobile Page and Show Details. This block handles the Show Details option.

If you've ever wanted to show additional information to someone after they tap a notification, you can! The content you enter into the Additional Details box will be shown in the app via this block. Start by creating a new page and adding the Communication View block. Next, you'll need to tell the app which page has this block so it knows where to direct people that tap on notifications. Under the Application tab, click Edit and select the page you created for Communication View Page.

Configuration

Allowed SMS Numbers

This setting allows you to designate which phone numbers are permitted as From numbers. If no numbers are selected, all numbers will be available.

Show Only Personal SMS Number

When this setting is turned on, only SMS numbers associated with the current person will display. Administrators, however, will be able to view all SMS numbers.

Hide Personal SMS Number

Enable this setting to only show SMS numbers that aren't linked to a specific person - essentially, numbers without an "Assigned To Person" value.

Show Conversations From Months Ago

Limits the conversations shown to those of X months ago or newer.

Max Conversations

The max number of conversations to show in the panel.

Database Timeout

The number of seconds to wait before reporting a database timeout.

Conversation Page

Person Search Stopped Typing Behavior Threshold

The amount of time to wait before executing the person search command, from the millisecond that the person stops typing.

Page Parameters

The following query string parameters are recognized and utilized by this block.

Styling

Block Configuration

Header Template

This is the content that is rendered above the lists of your requests. This allows you to put a logo, header, or do whatever you like to style the top of this component.

Type Template

This is the main template that is used to display the entire list of your connection types. You can fully customize this template using the entire list object to do whatever you like with it.

Merge Fields

In the opportunity template, you have access to these objects:

No Requests Content

You may have noticed in some other blocks, there is a block setting to provide content when there is nothing to display. Often seen as something like a:

<NotificationBox Text="There are currently no connection types. Please check again later." />

We have decided to make this an even easier piece of the puzzle to set, by including it in the template itself. If you wish to customize this content, the piece you are looking for is:

{% if ConnectionTypes == empty %}
    ... Put your content here!
{% endif %}

Detail Page

This is the page that is linked when a specific request is selected. You can see it being used here in the default template.

{% if DetailPage != null %}            
    <Frame.GestureRecognizers>
        <TapGestureRecognizer Command="{Binding PushPage}" 
            CommandParameter="{{ DetailPage }}?ConnectionTypeGuid={{ type.Guid }}" />
    </Frame.GestureRecognizers>
{% endif %}

Block Configuration

The only thing required for this block to function is the RequesterId. This can be the string IdKey or Guid of the Requester.

Connection Types

The connection types that will be made available to this block. If none are selected, all available connection types will be shown.

Post Save Action

The navigation command to execute after a save successfully occurs.

Post Cancel Action

The navigation command to execute when the "cancel" button is pressed.

Page Parameters

Getting Content

3. Navigate to the page containing the COL block, and tap!

Getting the connection opportunities

In order for the block to know which 'Connection Opportunity' to display requests for, you need to give it some context. Navigate to 'Admin Settings > Power Tools > SQL Command' and execute the following query:

SELECT Name,Guid FROM [ConnectionOpportunity]

If there are any connection opportunities available, this will display a list containing their name and guid. Select and copy the guid of the specific connection opportunity you are trying to display requests for. In this walkthrough, I will be using the 'Greeter' connection opportunity guid.

Using query parameters

To provide the guid we just obtained to the block, we do so by providing it with 'query parameters', which are context passed to the block when the page containing this block is pushed. This block looks for the following query parameters:

{% assign pageGuid = 'c327bdc5-dc76-4408-baa4-c4a2d022ed36' %}
{% assign connectionOpportunityGuid = 'dd565087-a4be-4943-b123-bf22777e8426' %}

<Button Command="{Binding PushPage}">
    <Button.CommandParameter>
        <Rock:PushPageParameters PageGuid="{{ pageGuid }}">
            <Rock:Parameter Name="connectionTypeGuid" Value="{{ connectionOpportunityGuid }}" />
        </Rock:PushPageParameters>
    </Button.CommandParameter>
</Button>

Deploy, press that button, and voila! The block should display the list of connection opportunities for the specific type. So now you can see how to show the opportunities for one specific connection type... but that would rarely be the actual intended use case.

Block Configuration

Header Template

This is the content that is rendered above the lists of your requests. This allows you to put a logo, header, or do whatever you like to style the top of this block. Please note, that if a ConnectionOpportunity is not found, this content will not display.

Merge Fields

Merge fields are fields that are available to use within the template. So in the header template, you have access to these objects:

Request Template

This is the main template that is used to display the entire list of connection requests. You can fully customize this template using the entire list object to do whatever you like with it.

Merge Fields

In the request template, you have access to these objects:

No Requests Content

You may have noticed in some other blocks, there is a block setting to provide content when there is nothing to display. Often seen as something like a:

<NotificationBox Text="You currently have no current requests. Please check again later." />

We have decided to make this an even easier piece of the puzzle to set, by including it in the template itself. If you wish to customize this content, the piece you are looking for is:

{% if ConnectionRequests == empty %}
    ... Put your content here!
{% endif %}

Detail Page

This is the page that is linked when a specific request is selected. You can see it being used here in the default template.

{% if DetailPage != null %}            
    <Frame.GestureRecognizers>
        <TapGestureRecognizer Command="{Binding PushPage}" 
            CommandParameter="{{ DetailPage }}?ConnectionRequestGuid={{ request.Guid }}" />
    </Frame.GestureRecognizers>
{% endif %}

When saving a new app, or selecting an existing one from the list, you'll be taken to the Application page. The title bar will show the name of your app on the left and the Site/App Id on the right, as well as the deployment status. Underneath you'll find tabbed navigation for the different areas of your app and some of the configuration values you previously selected.

To begin adding content to our app we need to navigate to the Pages area. The homepage has already been created for you. Selecting this page will bring you to the page details area where you can change the configuration and add blocks, similar to the process on Rock web.

Let's add our first block by selecting the Content block and dragging it into the Main section.

Once added click the Gear icon to change the block properties. In this Content block we'll add our first lines of XAML. Let's add a label and card to our page with the XAML below:

<StackLayout StyleClass="p-16"
    Spacing="16">
 
    <Label Text="News Feed"
        StyleClass="h4" />
    
    <Rock:ContainedCard Image="https://realchip.rocks/Content/Chip%20Rocks/Images/Chip%20Sticker@4x.png"
        Tagline="ANNOUNCEMENT"
        Title="Welcome to Rock Mobile"
        ImageRatio=".75:1">
        Check out just how easy it is to create a new mobile app for your organization...
    </Rock:ContainedCard>
    
</StackLayout>

Below the content input are some options for enabling Lava commands and selecting if block is Dynamic Content. If enabled, making changes to the XAML content will be shown upon refresh of the page instead of requiring a full redeploy.

Clicking Save will add our XAML to the block. Now let's deploy our application and view it on a device.

Deployment

Navigating to the Application page for your app shows the deployment status in the top right. New apps start as Not Deployed, so you'll need to click the Deploy button in the bottom right corner to test your app. The first deploy may take a few moments, but generally this process happens quickly.

Note that making changes to the app (like adding new pages and blocks or changing block settings and application colors) will require you to Deploy again, as well as reloading the app, to see the changes. Changes to Content blocks that have a Dynamic Content value of Yes will be shown without a new deployment. When a user opens the app and is shown the splash / launch screen the app is pulling the latest deployment from your server (or wherever your bundle is hosted).

Testing

The best way to test your application is using the Rock Mobile Core app available on the app stores.

Simply tap and hold the screen with two fingers and a small popup with app information will appear. Tapping the App Switcher button will allow you to change the server to which the app connects.

The App Switcher page has three fields that are required to connect to your server. All of this information can be found by navigating to the application's internal page (under Home > CMS Configuration > Mobile Applications) and selecting your app. Let's take a look at each of them.

Application Id

This is the ID given to the application by Rock when it is created. It cannot be changed. To find your application ID, navigate to the Application page and find the Site/App Id in the top right. Alternatively, you can see the number in the URL bar.

API URL

API Key

This was configured when creating your application. You can change this value during development, but any apps using this key will need to update their App Switcher page in order to connect again.

When finished, your form will look something like this:

Tap the Launch App button to connect and view your app. The App Switcher page will remember what you've entered so you only have to do this once.

Rock Core App Connection

You can always connect back to the original Rock Mobile Core app if needed:

App Id 36

API URL https://www.rockrms.com/api

API Key rocksolidpihc

Publishing

When it comes time to publish your app into the stores, get started with App Factory.

This Content Collection View block is designed to bring your content collections to life. It offers powerful search and filtering tools that work across all items in your collection, delivering results at incredibly fast speeds. Learn more about Rock's Content Collection feature here in the manual:

Bindings

<Rock:Divider IsVisible="{Binding IsLastItem, Converter={Rock:InverseBooleanConverter}}" />

Parameters

Settings

This block allows you to quickly create a note from anywhere in your application. This note will not be tied to anything specific -- and has a default Note Type of Quick Note. You can use the My Notes block to later view and comprehensively manage the note.

Block Configuration

Note Type

The note type to use for the newly created Quick Note.

Placeholder Text

The text to use as the placeholder for the quick note.

Block Configuration

Category

The attribute category to display the values of. Currently, this list shows all of the attribute categories. It is up to you to ensure that the selected Entity Type and Attribute are compatible.

Use Abbreviated Names

If true, and the attribute has an abbreviated name, that will be used in place of the attribute name.

Entity Type

The type of entity to fetch attributes for. This also becomes the Entity Type set as a context parameter.

This section refers to the 'Events' mobile block group.

This section refers to the 'Finance' mobile block group.

Getting Started

A little bit of forewarning for when jumping into this block is that it has been pre-configured to function with the 'Person Name' search component. If you plan to change the component type, a decent understanding of XAML will have to be incorporated into the Result Item Template to use the ItemType.

The good news is that if that is the intended functionality, it works right out of the box, as long as you set the Search Component to Person Name.

Settings

Styles

<StackLayout.GestureRecognizers>
    <TapGestureRecognizer Command="{Binding AppendSearchHistory}">
        <TapGestureRecognizer.CommandParameter>
            <!-- We should pass in the Guid (of the entity that we are saving)-->
            <Rock:AppendToSearchHistoryParameters Guid="{{ Item.Guid }}">
                <!-- These are parameters that become available as merge fields 
                to the Historical Result Item Template -->
                <Rock:Parameter Name="Name" Value="{{ itemName }}" />
            </Rock:AppendToSearchHistoryParameters>
        </TapGestureRecognizer.CommandParameter>
    </TapGestureRecognizer>
</StackLayout.GestureRecognizers>

These items then utilize the Historical Result Item Template, so you can save any related entity information to have full customization over your recent searches.

Overview

In order to get content for our notes block, we need to do a couple of things. In this section, we will walk through the steps necessary to display notes of a specific entity by:

1. Adding a note to a Person entity.

2. Configuring the block settings.

3. Configuring the context parameter.

4. Passing in a GUID as a page parameter.

Adding a Note to an Entity

In order to get started, we need to make sure that we actually have a note to display. On your Rock server, navigate to a person's profile page (using the search in the top right is a fast and easy way) and press the add button to add a note. I would recommend adding a note to yourself, as you know that you will have permission to view it.

From here should be pretty self-explanatory. Go ahead and add a note with whatever text you wish, and press Save Note.

Configuration

Block Settings

Next, we need to configure our block to actually look for those personal notes. In the block settings, set the Entity Type to Person and in the Note Types, select Person: Personal Note.

So now, the block knows the entity type that we are fetching notes for, and also the specific note type we are fetching.

If enabled, a toggle will display that allows an individual to mark a Note as alert.

If enabled, a toggle will display that allows an individual to mark a Note as private.

Context Parameter

Next, we need to configure the page settings to look for a PersonGuid as a context parameter. We do this by heading to the page settings, which can be navigated to by pressing the Edit button above the mobile page builder.

Once in the page detail, underneath Advanced Settings, you should see a Context Parameters section. If you do not see this setting, please try refreshing the page and potentially clearing your cache. Set this to PersonGuid so the page knows that we are attempting to pass in a person guid as the context parameter.

Passing Context

1. Navigate to our page containing the Notes block.

2. Passes in the PersonGuid as a query string parameter.

For number one, we will need to obtain the PageGuid of the page containing our Notes block. Luckily, there is a handy feature that lets you do this easily. Press the little blue icon in the top right of your mobile page editor, as seen here:

Once obtained, go back to our blank page with nothing but the content block, and set the content to the following XAML:

{% assign pageGuid = 'your page guid' %}

<Button Text="Notes!" Command="{Binding PushPage}">
    <Button.CommandParameter>
        <Rock:PushPageParameters PageGuid="{{ pageGuid }}">
            <Rock:Parameter Name="PersonGuid" Value="{{ CurrentPerson.Guid }}" />
        </Rock:PushPageParameters>
    </Button.CommandParameter>
</Button>

Simply replace the pageGuid to the one you just copied, and you are good to go.

Launch the application, and tap the button we just created. You should see a similar outcome:

Using a Template

In many cases, you may want to incorporate Notes into another layout. That's why we introduced an option for you to customize the Notes block using your own XAML template.

To use a custom template, you must enable the Use Template block setting. When this setting is enabled, the Page Load Size becomes the amount of notes (ordered by recency) supplied to the template. It is recommended to keep this as a relatively low number. You can set a Note List Page block setting that is meant to direct to a page containing the Notes block in a full-screen manner (not using a template). The following commands and merge fields become available to you in the Notes Template:

Recommended Layout

This block applies integrated scroll and internal padding. The recommended layout for this block is a simple, clean layout that lets the block do most of the work:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:Rock="clr-namespace:Rock.Mobile.Cms;assembly=Rock.Mobile"
             xmlns:Common="clr-namespace:Rock.Mobile.Common;assembly=Rock.Mobile.Common">
            <Rock:Zone ZoneName="Main" />
</ContentPage>

Block Configuration

Note Item Template

This template is pretty complicated. It is what is displayed for each note item in the list. There are a handful of merge fields and commands that you can use to customize this template.

Merge Fields

Commands

Enable Swipe for Options

If enabled, the note will be both left and right swipe-able with options to add a reminder, connection, link to person, edit or delete.

Person Note Types

The note types to allow when linking a note to a person. If none are checked, all of the note types will be included.

Reminder Note Type

The note type to update the note to when adding a reminder from the note.

Connection Note Type

The note type to update the note to when adding a connection request from the note.

Person Profile Detail Page

The page to use to view the details of a person.

Reminder Detail Page

The page to use to edit or add a reminder.

Add Connection Page

The page to use when adding a new connection from the note.

Connection Detail Page

The page to use when viewing the details of a connection request.

Group Notes by Date

Whether or not the notes should be grouped by the date they were left.

Note Items

Configuration

Destination Page

Login Page

The page to use when showing the login page. If not set, then the Login page provided in the Application settings will be used.

Show All

This should really only be used for testing, and hidden from public view. When enabled, all active occurrences will be shown.

Always Request Location

When enabled, the device location will always be requested. If disabled, then the location will only be requested dependent on whether or not the person has already been requested in the past.

Template

The template to use when rendering the content.

Merge Fields

The following merge fields are available to you in the template.

Refresh Interval

When assigned a value more than 0, the block will self-refresh at regular intervals, specifically every Refresh Interval seconds, but only if the block is visible on the page. It's generally advised not to set the value under 60 (with the exception of 0, which deactivates it).

Parameters

Settings

Calendar

The calendar to pull events from.

Detail Page

The mobile page to push onto the navigation stack when viewing details of an event. This will not work with an external web page.

Event Template

The template to use when rendering event items.

Merge Fields

In the template, you have access to these objects:

Day Header Template

The XAML to use when rendering the day header above a grouping of events.

Enable Campus Filtering

If enabled then events will be filtered by campus to the campus context of the page and user.

Show Past Events

When enabled past events will be included on the calendar, otherwise, only future events will be shown.

Styling

Defining Animations

Let's talk about simple animations first. Animations are referenced by name and defined in the Resources of an element. In order to access an animation, it must be defined in an ancestor of where you are trying to reference it. Said another way, let's suppose you have the following XAML defined:

If you wanted to apply an animation to the label called myLabel then you would need to define it on either the StackLayout or the ScrollView. As long as it's defined above the element you are going to be referencing it from then you are fine. You cannot define it on the element itself.

So let's take an example of what this might look like:

This defines an animation that references myLabel as the target of the changes it will be making. The animation is going to be changing the Opacity property of the label over a duration of 2,000 milliseconds (2 seconds). Finally, it will change the opacity of the label from its current opacity to the target opacity of 0. Note, this only defines the animation, it doesn't actually trigger it.

These types of animation definitions let you target specific visual elements with a pre-defined animation style.

Starting Animations

Okay, we were able to define an animation but we need to start it somehow. You have two choices when it comes to triggering an animation.

1. Trigger style in response to the user doing something.

2. Automatically when the view loads (behavior style).

Let's modify our example above but include a trigger style activator based on the user tapping a button:

We've added a button and a BeginAnimation trigger to it that starts the FadeOut animation we previously defined. Now, when the user taps the Fade button, the label above will slowly fade out over 2 seconds.

Another way we could define this is by behavior. Suppose we wanted the text to automatically fade out after the page loads? To do that we would use a BeginAnimationBehavior instead:

The way behaviors work is that they begin when the element they are attached to are themselves attached to their parent element. Because there might be a delay between when this happens and when the page itself becomes fully visible, there is a hard-coded 250-millisecond delay before the referenced animation actually begins.

Stopping Animations

You can also provide the ability to stop an animation by using a trigger. Technically, the library also supports stopping an animation using a behavior, but in our use case, those don't actually make sense. If you are curious though, it is available as EndAnimationBehavior. But here is an example of two buttons, one to start and one to stop an animation.

Triggered Animations

Triggered animations are ones that are, well, triggered by some user interaction. Until the user activates that trigger event, such as tapping a button, the animation remains idle.

All of the animations in this section support the following properties.

BounceInAnimation

Animates the Scale and Opacity of the target to make it appear.

BounceOutAnimation

Animates the Scale and Opacity of the target to make it disappear.

BackgroundColorAnimation

Animates the BackgroundColor of the target from its current value to a new color.

ColorAnimation

Animates the specified property of the target, which must be of type Color, between two values.

CornerRadiusAnimation

Animates the specified property of the target, which must be of type CornerRadius, between two values.

DoubleAnimation

Animates the specified property, which must be of type double, of the target between two values.

FadeInAnimation

Animates the Opacity and Y position of the element to make it visible. As the element is faded in it will also slide down or up to its final position.

FadeToAnimation

Animates the Opacity of the target from its current value to a new value.

FadeOutAnimation

Animates the Opacity and Y position of the element to make it invisible. As the element is faded in, it will also slide down or up from its current position.

FlipAnimation

Animates the Opacity and RotationY axis of the element to make it visible. As the element is faded in it will also rotate along its y-axis (that is, it will grow from a single vertical line to full-width) as if a card were being turned 90 degrees.

HeartAnimation

Animates the Scale of the target to simulate a heartbeat, growing and shrinking slightly.

IntAnimation

Animates the specified property of the target, which must be of type int, between two values.

JumpAnimation

Animates the TranslationY of the target to cause it to jump up and down.

RelRotateToAnimation

Animates the Rotation of the target to spin the element by the number of degrees. This rotation happens along the Z-axis, meaning it does not distort the element's perspective at all.

RelScaleToAnimation

Animates the Scale of the target to make the element appear larger or smaller than it normally would.

RotateToAnimation

Animates the Rotation of the target to spin the element to the specified final rotation value. This rotation happens along the Z-axis, meaning it does not distort the element's perspective at all.

RotateXToAnimation

Animates the RotationX of the target to shift the perspective of the element.

RotateYToAnimation

Animates the RotationY of the target to shift the perspective of the element.

ScaleToAnimation

Animates the Scale of the target to make the element appear larger or smaller than it normally would.

ShakeAnimation

Animates the TranslationX target to make it appear as if it were being shaken back and forth.

ThicknessAnimation

Animates the specified property of the target, which must be of type Thickness, between two values.

TranslateToAnimation

Animates the TranslationX and TranslationY properties of the target to shift the element around from its normal position.

TurnstileInAnimation

Animates the RotationY and Opacity properties of the target to give a turnstile effect to the element appearing on the screen.

TurnstileOutAnimation

Animates the RotationY and Opacity properties of the target to give a turnstile effect to the element disappearing from the screen.

GroupAnimation

This special animation does not conform to the common properties mentioned previously. This element lets you group animations so that they can be triggered at the same time. Animations to be grouped together can be added as child elements.

Passive Animations

A passive animation is one that is always active and updates continuously whenever the property it uses to track progress changes. One example usage of this might be a slider that is used to specify the color of something. As the slider moves from one side to the other, the color slowly changes from one color to the other.

All of the animations in this section support the following properties.

AnimateProgressColor

Animates the Color-type property between the From and To values.

AnimateProgressCornerRadius

Animates the CornerRadius-type property between the From and To values.

AnimateProgressDouble

Animates the double-type property between the From and To values.

AnimateProgressInt

Animates the int-type property between the From and To values.

AnimateProgressThickness

Animates the Thickness-type property between the From and To values.

Load Animations

EntranceTransition

Provides the animated transition behavior on controls when they first appear. You can use this on individual objects or on containers of objects. In the latter case, child elements will animate into view in sequence rather than all at the same time.

Query Parameters

The query parameters this block looks for upon initialization are as follows.

Block Configuration

List Title

The title to make available in the lava.

Audience

The audience to show calendar items for.

Calendar

Filters the events by a specific calendar.

Campuses

List of which campuses to show occurrences for. This setting will be ignored if Use Campus Context is enabled.

Use Campus Context

Determine if the campus should be read from the campus context of the page.

Date Range

Optional date range to filter the occurrences on.

Max Occurrences

The maximum number of occurrences to show.

Event Detail Page

The page to use for showing event details.

Lava Template

The template to use when rendering event items.

Merge Fields

In the template, you have access to these objects:

Enabled Lava Commands

The Lava commands that should be enabled for this block, only affects Lava rendered on the server.

This block displays a specific event item occurrence.

Page Parameters

The block looks for the following page parameter.

Block Configuration

Registration URL

The base URL to use when linking to the registration page.

Template

The template to use when rendering the event.

Merge Fields

In the template, you have access to these objects:

Merge Field Types

This merge field has a couple of unique types, EventItemOccurrence and Event. Here are their usable properties.

EventItemOccurrence

EventItem

Query Strings

Merge Fields

In the template, you have access to these objects:

Styling

Supported Search Components

These are the only supported search components by the block. Using an unsupported search component will result in an error message to be displayed in place of search results.

Block Configuration

The following options are available for configuration.

General Settings

The general settings for this block are as follows.

Search Component(s)

Select any number of the supported search components you would like to display as a search option.

Header Content

The content to be displayed above the search field. SearchComponent is available as a merge field. Lava is processed on the client.

Footer Content

The content to be displayed above the search field. SearchComponent is available as a merge field. Lava is processed on the client.

Result Size

The number of results to initially return and with each sequential load (as you scroll down).

Auto Focus Keyboard

Determines whether or not the keyboard should automatically open when the block comes into view.

Show Search History

Whether or not to display search history. This will be limited to "per-component".

Person Search Settings

These settings are specific to search components that return people.

Show Birthdate

Whether or not to display the Person's birthdate in the search result item.

Show Age

Whether or not to display the Person's age in the search result item.

Person Detail Page

The page to link to when a Person search result item is pressed.

Group Search Settings

These settings are specific to search components that return groups.

Group Detail Page

Group search only. The page to link to when a Group search result item is pressed.

Configuration

Live Experience Web Page

Always Request Location

If enabled, the location will always be requested. If not, the OS will only prompt them for location dependent on whether or not they have been asked.

Keep Screen On

If enabled, the screen display will be marked to keep active while a Person is active in a Live Experience.

Page Parameters

What is Microsoft Entra

Setup

To ensure Entra works perfectly in Rock Mobile, follow this step-by-step guide.

2. Add permissions for our mobile application to retrieve necessary data points.

3. Ensure our authentication returns enough information to the Rock server.

4. Configure your Rock Mobile to support Entra.

1. Registering the app

b. Configure the Register an application screen considering the information below.

Name

Provide a name for your Rock Mobile app registration. Nothing really hinges on this.

Supported account types

This is really up to you. If you're limiting Entra login to staff, then the Accounts in this organizational directory only is likely the right choice.

Redirect URI

This is important. This needs to be formatted like <BundleId/PackageName>://entra/callback, otherwise authentication won't work. If your bundle identifier and package name differ, you'll have to add a Redirect URI for both (App Registrations > Your App > Authentication).

Ensure that the type of Redirect URI is set to Public client/native (mobile & desktop).

2. Add necessary permissions

We need to ensure that our mobile application has permission to see the necessary data of a newly authenticated user.

a. Navigate to your newly created app registration, then to API permissions > Add a permission.

b. Select Microsoft Graph.

c. Select Delgated permissions, check email, openid and profile permissions. Press Add permissions.

3. Add optional claims

Out of the box, Entra will not return the first name and last name of an authenticated person to the shell. Rock needs this information to process/person match etc., so we need to go in and add these data points.

a. Under your newly created app registration, navigate to Token configuration > Add optional claim.

b. Select ID as the Token type, and check email, family_name (last name) and given_name (first name). Press Add.

4. Configuring Rock Mobile

a. Jump into your Rock Mobile application (CMS Configuration > Mobile Applications > Your application > Edit).

b. In the Authentication Settings section, we're going to be configuring the Microsoft Entra settings.

Entra Client ID & Entra Tenant ID

Microsoft Entra Authentication Provider

c. Configure the Login block to provide Entra as an SSO option.

Supported Claims

The following identity claims are supported and can be utilized to supply additional information about a Rock Person. Since Entra configurations can vary, we supply a few different keys that are recognized and translated accordingly.