EduRoomSDK 0.2.1

EduRoomSDK 0.2.1

Maintained by Nicky Weber.



  • By
  • NickyWeber

EduRoom SDK for iOS

Version License Platform

Introduction

The EduRoom SDK for iOS enables a third party app to be available in 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 EduRoom and your app work together

The EduRoom app opens your app by making use of custom URL schemes. After successfully opening your app the SDK is kicking in and sends a heartbeat HTTPS request to the EduRoom backend to signal that a student is active.

When teachers choose to include your app in their lessons, it will be displayed in the EduRoom app. Upon tapping your app it will try to open it. If it is not installed on the device yet, the student is redirected to the app store to download it.

How to register

You can easily register your app at https://eduroom.de/developer/ios-sdk/.

You need to define a few properties before registration though! Please read on for details.

We will review your submission and publish it as soon as possible.

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.

If you don't have an identifier yet, you can register again or provide the missing id by sending an email to [email protected]. Please provide the name and custom url scheme of your app.

Installation & Examples

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

pod 'EduRoomSDK'

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 git clone https://github.com/EdumodeOrg/EduRoomSDK-iOS.git
  • CD to folder Example
  • run pod install from the Example directory first.
  • open EduRoomSDK.xcworkspace in XCode

Integrating the SDK

Everything is taking place in the AppDelegate class.

1. Import the the EduRoom SDK

Swift

import EduRoomSDK

Objective-C

@import EduRoomSDK;

2. Create a persistent instance of EduRoom

The EduRoom instance should be created only once as soon as the app has launched successfully. Example:

Swift

class AppDelegate: UIResponder, UIApplicationDelegate {

    var eduroom: EduRoom?
    
    // ...
    
    func applicationDidFinishLaunching(_ application: UIApplication) {
		// ... 
		eduroom = EduRoom()
		// ...
		return true
    }
 
 	// ...   
}

Objective-C

@interface AppDelegate ()

@property (nonatomic, strong) EduRoom *eduroom;

@end

// ...

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	// ... 
	self.eduroom = [[EduRoom alloc] init];
	// ... 
	return YES;
}

3. Start a session when your app is opened by EduRoom

The main entry point is UIApplicationDelegate's application(_:open:options:) method.

application(_:didFinishLaunchingWithOptions:):

Swift

func application(_ app: UIApplication, open url: URL,
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    
    guard let source = options[.sourceApplication] as? String else {
        return false
    }
    
    // Catch all other schemes before calling eduroom.startSession(...)
    // as the SDK may try to open EduRoom if the source is mismatching or other errors occur

    eduroom?.startSession(source: source, url: url)
    
    return true
}

Objective-C

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    NSString *source = options[UIApplicationOpenURLOptionsSourceApplicationKey];
    if (!source) {
        return NO;
    }
    
    // Catch all other schemes before calling eduroom.startSession(...)
    // as the SDK may try to open EduRoom if the source is mismatching or other errors occur

    [self.eduroom startSessionWithSource:source url:url];
    
    return YES;
}

App resources used by the SDK

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

  • The SDK will disable the app idle timer when a session starts. 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. The timer is enabled again when a session stops.

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!

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.

You can add a little obstacle to prevent pulling down on the status bar by overriding preferredScreenEdgesDeferringSystemGestures in your view controllers:

Swift

override var preferredScreenEdgesDeferringSystemGestures: UIRectEdge {
    get {
        return .all
    }
}

Objective-C

- (UIRectEdge)preferredScreenEdgesDeferringSystemGestures
{
    return UIRectEdgeAll;
}

Sadly, iPhone X models will always hide the status bar in lanscape orientation.

Bugs & Feedback

Please use project's Github Issues.

Author

Nicky Weber, [email protected]

License

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