Swiftpack.co - Package - EdumodeOrg/EduRoomSDK-iOS

EduRoomSDK for iOS

Version License Platform

Introduction

The EduRoom SDK for iOS enables a third party app to be available for EduRoom lessons.

The EduRoom app works as a hub to link to third party apps and web content.

Supported languages: Swift and Objective-C.

How linking to third party apps work

The EduRoom app opens a third party app using custom URL schemes. After successfully opening the third party app the SDK is kicking in and sends a heartbeat to the backend to signal that a student is active.

When teachers choose to include a third party app in their lessons, the app will be displayed in the EduRoom app. Upon tapping the entry the app tries to open the third party app via custom URL scheme. If this fails, the student is redirected to the app store to download the third party app.

How to register

A third party app has to be registered in the EduRoom backend. At the moment this is a manual task. Please provide the following information and send it to sdk@eduroom.de:

  • Name of the app
  • Custom URL scheme
  • App Store identifier (if available)
  • Android version's package name (optional)

Android version available?

Please provide the the package name If you have an Android version of your app available on Google Play Store. The package name allows us to easily match iOS and Android versions when searched for by teachers.

Recommendations

If possible show the status bar for every orientation. Experience shows that students check time of day several times per lesson. iOS will hide the status bar in landscape orientation and thus the clock. As some apps offer the best user experience when used in landscape orientation a student will pull down the message center to see the clock again not aware that this will result in backgrounding the app. This leads to potential missed out ping requests required to keep a student active in a lesson.

iPhone X models will always hide the status bar in lanscape orientation. To mitigate this you can implement your own way to show the clock and battery life.

Custom URL Scheme

Please choose a unique scheme to avoid collisions. Usually the bundle identifier is a good choice for a custom URL scheme, e.g. com.mycompany.myapp://

You register a custom URL scheme for your app by following Apple's official instructions.

App Store identifier

You can find your App Store identifier using the Apple's Link Maker. Search for your app and then inspect the direct link at the bottom. The identifier is the number after the string id.

Example: https://itunes.apple.com/de/app/eduroom-sch%C3%BCler-app/id1441459022?mt=8 the App Store identifier is: 1441459022.

Installation & Examples

After including the SDK please have a look at the example projects for Swift and Objective-C. In the AppDelegate.swift or AppDelegate.m files you can find a reference integration of the SDK.

To run the example project, clone the repo, and run pod install from the Example directory first.

EduRoomSDK is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'EduRoomSDK'

The main entrance point is UIApplicationDelegate's application(_:open:options:) method. As soon as this method is called, due to the EduRoom app opening the third party app, the SDK instance needs to be created with the given URL and the source application. The SDK instance is now being configured with the current session of the student. If everything worked out, a ping session is started.

Two more UIApplicationDelegate method need to be implemented:

Once again, example projects for Swift and Objective-C are in the folder Examples.

Requirements

As soon as the SDK instances error handler is invoked, the third party app must show a message to the user. It is up the third party app developer on how to present an error message. See examples. Default texts and translations are provided by the SDK.

App resources used by the SDK

  • The SDK sends a regular heartbeat ping HTTPS request to the backend. An ephemeral internal URL session is used to send the requests.

  • The SDK will disable the app idle timer upon instantiation. This is a precaution to keep the ping active while a student may not use the third party app for the length of a whole lesson. As soon as the ping stops, you can reset the value back to your defaults.

How to test

Make sure the following steps have been completed:

  • SDK integrated ✓
  • Your App registered ✓

Simple custom URL scheme test

To test your custom URL scheme, you can create a single view iOS app. Invoke the following code to see if your app including the EduRoom SDK is opened:

Swift

if let url = URL(string: "com.mycompany.myapp://test") {            
	UIApplication.shared.open(url, options: [:]) { (success) in
	     print(success)
	}
}

Objective-C

NSURL *url = [[NSURL alloc] initWithString:@"com.mycompany.myapp://test"];

[[UIApplication sharedApplication] openURL:url
                                   options:@{}
                         completionHandler:^(BOOL success) {
                                           NSLog(@"%d", success);
                                       }];

Full integration test

  1. Install your app including the EduRoom SDK on a device
  2. Get the EduRoom app from the App Store.
  3. Create a teacher account at edumode.org. Scroll to Lehrer-App kostenlos ausprobieren. Follow the instructions in the email.
  4. As student create an account in the EduRoom app
  5. As teacher create a group and invite the newly create student account with the provided QR code
  6. As teacher create a ruleset. Search for your app and include it.
  7. As teacher create a lesson. Set today's date and a broad time span. Set your newly created ruleset. Set your group. Click on Teilnehmerliste
  8. As student you can pull to update available lessons or just wait a few seconds. As soon as the lesson appears tap it. Your app should appear. Tap it, a system dialog should popup asking you if you want to open the app. Upon accepting your app should open.
  9. As teacher the student should turn green

If the student stays green for a longer than a few minutes the ping is working as expected.

Congratulations!

Bugs & Feedback

Please use Github issues.

Author

Nicky Weber, nicky.weber@edumode.org

License

EduRoomSDK is available under the MIT license. See the LICENSE file for more info.

Github

link
Stars: 2
Help us keep the lights on

Dependencies

Used By

Total: