Getting Started
In setting up OpenID Connect (OIDC) you will generate some data to send to Subsplash. Subsplash will set up part of the authentication and then send data back to you to complete setting up your Communication Transport.
If you have any trouble setting up this plugin beyond the scope of this documentation, please contact your Customer Success Manager (CSM) or Account Manager (AM) and we will work through it with you. If you are not yet using Subsplash, please visit https://subsplash.com to learn more and connect with us.
Prerequisites:
Rock RMS Version 12.0 or higher
This version is necessary for the addition of OpenID Connect (OIDC)
Contact Subsplash
Please contact your Customer Success Manager (CSM) or Account Manager (AM) if you have not been talking with them. If you are not currently a Subsplash client, please connect with us at https://subsplash.com.
Key Terms
Subsplash App Key
This is available in your Subsplash Dashboard (https://dashboard.subsplash.com). Your App Key will be displayed near the bottom of this page.
Rock OIDC Credentials
You will generate a Client Id and a Client Secret in Rock to send to Subsplash.
Subsplash Auth Info
Shared via a secure document during the setup process.
Note: this Client Id and Client Secret are different from the ones you generate in Rock.
Push Notification Endpoint
Token Endpoint
App Key (should match the one you sent)
Client Id
Client Secret
Auth Provider ID
Create REST Key
If you are a Subsplash Giving user and use our Rock Integration you may recall setting up a REST key in doing so, please note that the same REST key should not be used for the notification plugin.
In your Rock Dashboard, navigate to Admin Tools > Security:
Click on REST Keys:
Add a REST Key by clicking on the plus sign on the right:
Create a new REST Key with the Name "Subsplash Plugin", click Generate Key to set the key, then click Save:
Navigate back to Admin Tools > Security and click on REST Controllers:
Find the Subsplash Controller (Controller Type: com.subsplash.Rest.Controllers.SubsplashController) and click on the Security lock icon on the right end of the row and you will see a modal popup (Note: clicking on the name or type will take you to a different screen):
Add View and Edit permissions. With View selected, click Add User and find the Subsplash Plugin user created above:
With Edit selected, click Add User and find the Subsplash Plugin user. Check that they have Allow selected. Click Done to close the modal:
Setting up OpenID Connect (OIDC)
To start, navigate to Admin Tools > Security > OpenID Connect Clients. Your page should look like the following screenshot:
Click on the “+” button on the bottom right corner to add a new OpenID Connect Client, and follow the steps below to create a new OIDC client:
Fill out the name as “Subsplash App Platform”
Make sure the “Active” checkbox is checked.
For Client ID, click “Generate Id”, and then copy that Id into a safe place. You will be providing this Id to Subsplash in a later step.
For Client Secret, click “Generate Secret”, and copy that secret into a safe place to give to Subsplash as well. Note: this is the only time you will see the client secret, so make sure you make note of it; otherwise, you will have to re-generate it.
For Redirect Uri, you can type or copy & paste the following URL: https://core.subsplash.com/end-user-auth/v1/authproviders/result
Set the Logout Uri to a page of your preference. Usually, this is pointed back to the home page of your church’s website, but this is your choice.
Lastly, make sure all options under the “Allowed scopes and Claims” are checked.
You can use the following screenshot as a reference to make sure you have everything, and when ready click “Save”:
Once completed, send the Subsplash App Key, Rock Client Id, and Client Secret via the secured document created by Subsplash. If you have not received this document, please contact your CSM. After you share that data, Subsplash will complete the setup on our side and share the remaining information needed via the secured document to complete Setting up your Communication Transport.
Preparing Rock for Subsplash
Rock, by default, has login screens set to the Stark theme under “External Website”. If you were to leave this setting where it is, then your mobile sign-in pages would look like the following screenshots.
Default theme
Default theme
If you like the look of these screens and would like to keep them as is, you can skip this part and set up your communication transport. If you would like to configure the login user experience that the user will see when authenticating with the Subsplash app, there are 2 different options:
If you already use Rock for your public website and your Subsplash app is themed similarly, it is likely you can simply reuse your existing login/registration pages with minimal changes.
You can use the default Rock Stark theme as it is configured out of the box with very minimal configuration changes. This could be as simple as setting up a DNS subdomain such as https://www.rocksolidchurchdemo.com/ and making sure this domain is configured for the external website site within Rock. When the user authenticates within the Subsplash app, they will simply be taken to the external website’s login page (https://www.rocksolidchurchdemo.com/login). By default, this page is preconfigured within Rock with all the registration, forgot account, and other pages. You may, however, want to disable some of the external pages that are not applicable for your organization.
Setting up your Communication Transport
To set up your communication transport, navigate to Admin Tools > Communication > Communication Transports
Click on the “Subsplash” communication transport, and a panel should pop up. Fill out the information we provided you, and make sure the “Active” dropdown is set to Yes. The following screenshot is an example of what it should look like once all settings are completed.
For your reference, you should have the following from us:
Push Notification Endpoint
Token Endpoint
Subsplash App Key
Subsplash Client Id
Subsplash Client Secret
Auth Provider Id
If anything is missing, please reach out to us again.
Once you have completed all settings, click “Save”.
Next, you need to activate push notifications. To do this, navigate to “Communication Mediums”. You can find the Communication Mediums page in Admin Tools > Communication > Communication Mediums
On the communication mediums page, click on “Push Notifications”. Then make sure “Active” is set to “Yes”, and select “Subsplash” as your “Transport Container”. The following screenshot shows what that looks like:
You have now completed the installation of the Subsplash Plugin!
Sending Notifications
At this point, your mobile app audience should be able to sign into their Rock account inside your app. If not, please revisit the setup of this documentation before moving on; this next step will not work without it. Additionally, to test individual push notifications, you should have at least one person signed into Rock through the mobile app.
Individual Notifications
To send an individual push notification, navigate to the Subsplash plugin within Rock in Admin Tools > Installed Plugins > Subsplash.
It should look like the following screenshot:
The “Individual(s)” tab will be automatically selected. You can select the individual(s) you would like to send a push notification to by clicking on the “Add Person” dropdown on the right-hand side.
Once you have your individual(s) selected, you can fill out the rest of the information as needed:
Title: This is the main body of your Push Notification. This text is displayed on the users’ lock screens, system notifications, and in the Inbox of the app.
Message: This is the additional text displayed within the app after the user taps on the Notification. If you know {{ Lava }}, then you can use the merge field (see below) to personalize your message.
Add Merge Field: This dropdown allows you to personalize your message with Lava. For example, if you would like to display a countdown of someone’s birthday, you can accomplish this by selecting the “Days to Birthday” merge field from the drop-down. Simply place the generated lava where you would like the information to appear in the body of your notification message.
Open Action: By default, when a user clicks on the notification, it will open the message directly within the app. If you would like the notification to open in a browser instead, simply select “Link to URL” and enter the URL.
Delay Send Until: As the name says, this simply delays the notification to be sent until the date entered. If you do not set a date, then the message will be sent as soon as possible once submitted.
Group Notifications
Like the individual push notification, you can send a notification to a group of people. The main difference here is that you can send a general notification to anyone who downloaded the app, whether they have logged into the app or not. You can also select from other group lists if you have them defined within the Subsplash dashboard.
To send a group push notification, navigate to the Subsplash plugin within Rock, and then select the “Notification Group” tab in Admin Tools > Installed Plugins > Subsplash:
By default, you should have a “General” group list available to you from the “Notification Group” dropdown. If selected, this will send a notification to anyone who downloaded your app.
Once you have your group selected, you can fill out the rest of the information as needed (just like the individual push notification):
Title: This is the main body of your Push Notification. This text is displayed on the users’ lock screens, system notifications, and in the Inbox of the app.
Message: This is the additional text displayed within the app after the user taps on the Notification. If you know {{ Lava }}, then you can use the merge field (see below) to personalize your message.
Add Merge Field: This dropdown allows you to personalize your message with Lava. For example, if you would like to display a countdown of someone’s birthday, you can accomplish this by selecting the “Days to Birthday” merge field from the drop-down. Simply place the generated lava where you would like the information to appear in the body of your notification message.
Open Action: By default, when a user clicks on the notification, it will open the message directly within the app. If you would like the notification to open in a browser instead, simply select “Link to URL” and enter the URL.
Delay Send Until: As the name says, this simply delays the notification to be sent until the date entered. If you do not set a date, then the message will be sent as soon as possible once submitted.
Communication History
Once notifications are sent, whether it is for an individual(s) or a group, you may want to see the statuses of your notifications. You will be able to see this in two separate places. The first one is within Rock, and the other is within the Subsplash dashboard under app notifications.
In Rock, you can find this communication history in People > Communication History.
Simply change the filters for “Communication Type” to “Push Notification” and click “Apply Filter”. After this, you should see a list of notifications and their statuses. Click on the message to see analytics along with the details of the notification:
On the Subsplash Dashboard, you can find this history by going to Apps > Push Notifications.
Then click on one of your notifications, and you will get a copy of what was sent from Rock.
Media
Version 1.1 of the Subsplash Plugin for RockRMS now allows for one-way sync of videos from your Subsplash Media library to RockRMS. Any media item uploaded and published in the Subsplash dashboard will automatically be synced into Rock and become available to embed as a Media Element. Subsplash does not currently support Libraries or Folders so all media will be imported into a “Media Items” folder.
Setup in Rock
In your Rock admin (v13 or newer), go to the toolbox menu, and select “CMS Configuration” in the menu. Then select Media Accounts and click the “+” button to add a new account that will be synced with Subsplash. Set the Account Type to “Subsplash Media Account” and then enter the following fields from the information you received from Subsplash:
App Key
Client Id
Client Secret
Syncing Media
By default, Rock’s “Sync Media” job will run every 2 hours and is configured to run a Full Sync every 24 hours and a quick sync otherwise. The quick sync will sync any media items that have been created or updated since the last time the job ran. This can be adjusted by updating the “Sync Media” job in the toolbox menu by navigating to System Settings → Job Administration → Sync Media.
There are two manual ways to sync media:
A full sync can be triggered manually using the download icon button in the Media Account configuration
Any place where a Media Element field type is used, both Folders and Media Elements can be synced using the refresh button.
Embedding Media
There are a couple of different ways to embed media. Using Subsplash’s media embed within a Content Channel is simple and easy but will require fetching a CustomUrl from Subsplash Dashboard. To find/change the Custom URL, follow these instructions:
Login to the dashboard: https://dashboard.subsplash.com/
Using the menu, navigate as follows: Web → Web App
In the “Basic Info” section, copy the Custom URL setting into the code below:
{% assign CustomUrl = '[Fetch from Subsplash Dashboard]' %} {% assign MediaItemShortCode = Item | Attribute:'MediaItem','SourceKey' %} <div class="sap-embed-player"> <iframe src="<https://subsplash.com/+{{AppShortCode}}/embed/mi/+{{MediaItemShortCode}}?audio&video&logoWatermark"frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe> </div> <style type="text/css"> div.sap-embed-player{position:relative;width:100%;height:0;padding-top:56.25%;} div.sap-embed-player>iframe{position:absolute;top:0;left:0;width:100%;height:100%;} </style>Using the default Rock short code, in a content channel is also possible by fetching the attribute’s raw value (guid) and passing it to the shortcode:
{% assign mediaElement = Item | Attribute:'MediaItem','RawValue' %} {[ mediaplayer media:'{{ mediaElement }}' autoresumeindays:'14' combineplaystatisticsindays:'14' width:'100%' ]}{[ endmediaplayer ]}
Syncing Analytics
Analytics for the Rock embed will be captured in Rock and then synced to Subsplash automatically when the Sync Media job runs. This sync is one-way and will show up in the Subsplash Dashboard as a Web Embed view:
FAQ and Troubleshooting
How long does a user stay logged into the mobile app from Rock?
The short answer is two weeks if the app has not been used within that timeframe.
By default, Rock has three different OIDC tokens used in the lifetime of a user’s login. For developer’s reference, this is Rock Core, so it is not configurable.
The first is the Identity Token, which is used during the authentication handshake. Once the user clicks that they want to log in and enters their credentials, that user must finish the entire login process within 20 minutes.
The second is the Access Token. When the access token expires, the application can use the refresh token to obtain a new access token. It can do this behind the scenes, and without the user’s involvement so that it is a seamless process for the user. This token is good for 1 hour.
Lastly, the Refresh Token. This is used to re-authenticate a session to get a new Access token. By default, this token is good for 2 weeks.
I can get to the login screen on the mobile app, but once clicked to login - then it fails.
In Rock, make sure your “Public Application Root - Global Attribute” is correct, and that it starts with “https”.
You can find this Global Attribute if you go to Admin Tools > General Settings > Global Attributes > Public Application Root. For your reference, here is a screenshot of what it might look like:
Make sure the Public Application Root value starts with “https://”, and that https is enabled. If you just made this change, make sure to restart Rock before trying again.
If you have any trouble setting up this plugin beyond the scope of this documentation, please contact your CSM and we will work through any issue with you.